هوک wp_head یکی از پرکاربردترین هوک‌های وردپرس برای تزریق متا تگ، استایل و اسکریپت پیش از بسته شدن تگ head است. این هوک پایه عملکرد افزونه‌های سئو، ابزارهای تحلیلی و کتابخانه‌های جاوااسکریپت محسوب می‌شود. استفاده درست از آن، از نبود متا تگ در گوگل، خطاهای JavaScript و ناسازگاری با افزونه‌های کش جلوگیری می‌کند. اشتباهات رایجی مانند نبود escape، نبود شرط، نبود priority و نبود تست موبایل می‌تواند تجربه کاربر و رتبه سایت را تضعیف کند. تسلط بر این هوک برای قالب‌نویسی و افزونه‌نویسی حرفه‌ای ضروری است و در سئو کاربرد جدی دارد.

چرا هوک wp_head نقطه حیاتی سایت است؟

تگ head در HTML، محل قرارگیری متا تگ‌ها، استایل‌ها، اسکریپت‌های همگام و لینک‌های مهم است. موتورهای جستجو، ابزارهای تحلیلی و مرورگرها از این بخش اطلاعات حیاتی دریافت می‌کنند. اگر متا تگ‌های مهم مانند description، canonical و Open Graph در این بخش درج نشوند، سایت شما در نتایج گوگل خوب دیده نمی‌شود، در شبکه‌های اجتماعی نمایش مناسبی ندارد و ابزارهای تحلیلی داده‌ای جمع نمی‌کنند. هوک wp_head نقطه استاندارد وردپرس برای تزریق این اطلاعات است.

هوک wp_head چیست؟

هوک wp_head یک اکشن هوک در هسته وردپرس است که در فایل header.php قالب، پیش از بستن تگ </head>، فراخوانی می‌شود. تمام افزونه‌هایی که به این هوک متصل هستند، در این نقطه کد خود را در HTML تزریق می‌کنند. نکته مهم این است که اگر قالب شما تگ wp_head() را فراخوانی نکند، هیچ افزونه‌ای نمی‌تواند در این بخش کد تزریق کند و بخش بزرگی از قابلیت‌های سایت از کار می‌افتد. این مسئله در قالب‌های سفارشی و آماتور رایج است.

ساختار و پارامترها

ساختار پایه اتصال به این هوک:
add_action( 'wp_head', 'mytheme_head_code' );
function mytheme_head_code() {
    // تزریق کد در head
}
این هوک هیچ پارامتر ورودی نمی‌گیرد. تمام منطق در بدنه تابع callback اجرا می‌شود. نکته مهم: تابع callback باید در functions.php قالب یا در فایل اصلی افزونه تعریف شود.

نقش priority در ترتیب اجرا

پارامتر دوم add_action، اولویت تابع callback است. مقدار پیش‌فرض ۱۰ است. این اولویت تعیین می‌کند که کد شما در چه ترتیبی نسبت به سایر کدها درج شود. کاربردهای رایج اولویت: - اولویت ۱ تا ۵: تزریق متا تگ‌های حیاتی که باید ابتدا درج شوند - اولویت ۱۰: ترتیب استاندارد - اولویت ۹۹ یا ۱۰۰: تزریق کدهای نهایی که باید در انتهای head قرار گیرند نمونه:
add_action( 'wp_head', 'mytheme_meta_tags', 1 );
function mytheme_meta_tags() {
    echo '<meta name="theme-color" content="#1a1a1a">';
}

add_action( 'wp_head', 'mytheme_custom_css', 100 );
function mytheme_custom_css() {
    echo '<style id="mytheme-custom-css">.site-header{background:#1a1a1a;}</style>';
}
نکته مهم: اگر می‌خواهید کد شما پس از کدهای افزونه‌های سئو درج شود، از اولویت بالاتر از ۱۰ استفاده کنید. برای مطالعه دقیق‌تر درباره هوک‌های مرتبط، به راهنمای هوک wp_footer و راهنمای هوک wp_enqueue_scripts مراجعه کنید.

کاربردهای عملی: متا تگ، CSS و JS

تزریق متا تگ viewport:
add_action( 'wp_head', 'mytheme_viewport_meta', 1 );
function mytheme_viewport_meta() {
    echo '<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">';
}
تزریق کد Google Analytics یا ابزار تحلیلی:
add_action( 'wp_head', 'mytheme_analytics_code', 20 );
function mytheme_analytics_code() {
    $ga_id = get_option( 'mytheme_ga_id' );
    if ( empty( $ga_id ) ) {
        return;
    }
    echo '<script async src="https://www.googletagmanager.com/gtag/js?id=' . esc_attr( $ga_id ) . '"></script>';
}
تزریق CSS حیاتی به‌صورت inline:
add_action( 'wp_head', 'mytheme_critical_css', 5 );
function mytheme_critical_css() {
    $css = '.site-header{position:sticky;top:0;} .hero{min-height:60vh;}';
    echo '<style id="mytheme-critical">' . wp_strip_all_tags( $css ) . '</style>';
}
نکته مهم: در تزریق CSS، از wp_strip_all_tags یا wp_kses استفاده کنید تا از تزریق کدهای خطرناک جلوگیری شود. راهنمای esc_html در صفحه esc_html آمده است.

هوک wp_head و سئو

افزونه‌های سئو مانند Yoast و Rank Math از این هوک برای تزریق متا تگ‌ها استفاده می‌کنند: - <title> تگ عنوان - <meta name="description"> توضیحات - <link rel="canonical"> نسخه اصلی - <meta property="og:*"> اوپن گراف - <meta name="twitter:*"> توییتر کارد - <script type="application/ld+json"> داده ساختاریافته اگر تابع wp_head() در قالب فراخوانی نشود، هیچ‌یک از این تگ‌ها درج نمی‌شوند و سایت شما در نتایج گوگل خوب دیده نمی‌شود. برای مطالعه بیشتر درباره داده ساختاریافته، به راهنمای Schema JSON-LD و راهنمای معماری اطلاعات برای سئو مراجعه کنید.

همکاری با افزونه‌های سئو

افزونه‌های سئو معمولاً از اولویت ۱ یا ۲ برای تزریق متا تگ‌ها استفاده می‌کنند. اگر کد شما با آنها تداخل داشته باشد، ممکن است متا تگ‌ها دو بار درج شوند یا با تأخیر ظاهر شوند. برای جلوگیری از تداخل، قبل از افزودن کد به wp_head، بررسی کنید که آیا افزونه سئو متا تگ مشابهی را درج می‌کند یا نه:
add_action( 'wp_head', 'mytheme_custom_og', 20 );
function mytheme_custom_og() {
    if ( defined( 'WPSEO_VERSION' ) ) {
        return; // افزونه Yoast مسئول است
    }

    if ( is_singular() ) {
        echo '<meta property="og:title" content="' . esc_attr( get_the_title() ) . '">';
        echo '<meta property="og:url" content="' . esc_url( get_permalink() ) . '">';
    }
}
این الگو از درج متا تگ تکراری جلوگیری می‌کند و امکان همکاری با افزونه‌های سئو را فراهم می‌کند.

نقش در Child Theme

در Child Theme، می‌توانید کدهای سفارشی خود را به wp_head اضافه کنید. اما نکته مهم این است که تابع wp_head() در فایل header.php قالب Parent فراخوانی می‌شود و اگر فایل هدر را در Child Theme کپی نکرده باشید، از Parent استفاده می‌شود. الگوی افزودن کد به Child Theme:
add_action( 'wp_head', 'mychild_head_code', 15 );
function mychild_head_code() {
    echo '<meta name="child-theme-active" content="true">';
}
نکته مهم: اگر قالب Parent از هوک wp_head استفاده نمی‌کند (که بسیار نادر است)، باید فایل هدر را در Child Theme کپی و تابع wp_head() را اضافه کنید. برای مطالعه درباره ساختار Child Theme به راهنمای get_header مراجعه کنید.

نکات امنیتی و اشتباهات رایج

اشتباه اول، نبود escape در خروجی است. هر داده پویا که در HTML تزریق می‌شود باید با توابع escape عبور کند. برای URL از esc_url و برای متن از esc_html یا esc_attr استفاده کنید. اشتباه دوم، نبود شرط است. اگر کد شما تنها در صفحات خاص نیاز است، از شرط‌هایی مانند is_singular یا is_front_page استفاده کنید. اشتباه سوم، نبود priority مناسب است. اگر می‌خواهید کد شما پیش از افزونه‌های سئو اجرا شود، اولویت پایین بدهید. اگر پس از آنها، اولویت بالا. اشتباه چهارم، نبود تست موبایل است. بعضی از متا تگ‌ها و کدهای تحلیلی تنها در موبایل کار می‌کنند. حتماً در دستگاه‌های مختلف تست کنید. اشتباه پنجم، تزریق کد JavaScript سنگین در head است. این کار رندر HTML را مسدود می‌کند و سرعت را کاهش می‌دهد. بهتر است اسکریپت‌ها را با wp_enqueue_script و پارامتر defer یا در فوتر بارگذاری کنید. اشتباه ششم، تزریق CSS حجیم در head است. برای CSS حیاتی، تزریق inline مناسب است اما برای بقیه استایل‌ها، از wp_enqueue_style استفاده کنید. اشتباه هفتم، فراموشی فراخوانی wp_head() در قالب است. اگر این تابع در قالب فراخوانی نشود، هیچ افزونه‌ای نمی‌تواند کد خود را درج کند.

تحلیل فنی پیشرفته

در نگاه مهندسی، هوک wp_head یک نقطه معماری در لایه رندر است که بر چند جنبه از سیستم اثر می‌گذارد. لایه اول لایه Integration است. تمام افزونه‌های سئو، ابزارهای تحلیلی و کتابخانه‌های جاوااسکریپت از این نقطه برای تزریق کد استفاده می‌کنند. بدون این هوک، اکوسیستم وردپرس به‌شدت محدود می‌شود. لایه دوم لایه Critical Rendering Path است. کدهایی که در head تزریق می‌شوند، پیش از رندر HTML اجرا می‌شوند. اگر این کدها سنگین باشند، رندر را مسدود می‌کنند و زمان First Contentful Paint را افزایش می‌دهند. لایه سوم لایه امنیت است. تزریق کد در head می‌تواند سطح حمله XSS را افزایش دهد. همیشه از توابع escape استفاده کنید و در صورت تزریق کد کاربر، از wp_kses استفاده کنید. لایه چهارم لایه کشینگ است. خروجی wp_head معمولاً کش می‌شود. اگر این خروجی بر اساس وضعیت کاربر یا صفحه تغییر کند، باید استراتژی کش مناسب انتخاب شود. لایه پنجم لایه SEO است. تمام متا تگ‌های سئو از این هوک تزریق می‌شوند. هماهنگی با افزونه‌های سئو از درج متا تگ تکراری جلوگیری می‌کند. لایه ششم لایه Performance است. ادغام کدهای inline و کاهش تعداد درخواست‌های HTTP در head می‌تواند سرعت را بهبود دهد. لایه هفتم لایه Multisite است. در شبکه‌های Multisite، هر سایت می‌تواند کد متفاوتی در head داشته باشد. لایه هشتم لایه تست است. تست‌های End-to-End باید مطمئن شوند که کد شما در همه صفحات به‌درستی درج می‌شود. مفاهیم پایه‌ای head در HTML head در ویکی‌پدیا توضیح داده شده است. برای مطالعه بیشتر روی توابع مرتبط، می‌توانید به راهنمای هوک wp_footer، راهنمای هوک wp_enqueue_scripts، راهنمای wp_enqueue_script، راهنمای wp_enqueue_style، راهنمای wp_localize_script، راهنمای get_header و راهنمای current_filter مراجعه کنید.

پرسش‌های پرتکرار

تفاوت wp_head و get_header چیست؟ اولی یک هوک در داخل فایل هدر است و دومی فایل هدر را بارگذاری می‌کند. آیا می‌توان چند بار این هوک را فراخوانی کرد؟ بله، با اولویت‌های مختلف، اما هر کد یک بار اجرا می‌شود. چطور فایلی را به head اضافه کنم؟ با wp_enqueue_style یا wp_enqueue_script، نه با تزریق مستقیم. آیا این هوک در پنل مدیریت اجرا می‌شود؟ خیر، در پنل از admin_head استفاده کنید. چطور از درج متا تگ تکراری جلوگیری کنیم؟ با بررسی تعریف افزونه سئو و شرط‌گذاری مناسب.

نتیجه و مسیر ادامه

هوک wp_head نقطه حیاتی تزریق متا تگ، استایل و اسکریپت در head وردپرس است. استفاده درست از آن یعنی انتخاب priority مناسب، escape در خروجی، شرط‌گذاری دقیق، هماهنگی با افزونه‌های سئو و تست در دستگاه‌های مختلف. اشتباه‌های کوچک در این هوک اغلب به نبود متا تگ‌های سئو، خطاهای JavaScript یا تداخل با افزونه‌ها منجر می‌شوند. اگر این هوک را در پروژه‌ای واقعی به کار برده‌اید و رفتار غیرمنتظره‌ای دیده‌اید — به‌خصوص در ترکیب با افزونه‌های سئو یا کش — تجربه‌تان می‌تواند راهگشای دیگران باشد. کدام بخش بیشترین زمان را از شما گرفت؟ دیدگاه خود را بنویسید.