مهم‌ترین هوک‌های WordPress کدامند و چه کاربردهایی دارند؟

اولین باری که یک هوک وردپرس را در پروژه‌ای واقعی شکستم، یک سایت فروشگاهی بود که بعد از آپدیت ووکامرس، دکمه افزودن به سبد خرید به‌طور کامل از کار افتاد و من سه ساعت فقط به‌دنبال این بودم که کدام `add_action` با یک نام تکراری، جریان اصلی را قطع کرده است. آن تجربه به من یاد داد که هوک‌ها، برخلاف ظاهر ساده‌شان، ستون فقرات معماری وردپرس هستند و بدون درک دقیق آن‌ها، هر پروژه جدی می‌تواند به یک بمب ساعتی تبدیل شود. امروز می‌خواهم به این پرسش پاسخ بدهم: مهم‌ترین هوک‌های WordPress کدامند و چه کاربردهایی دارند؟ اگر با مفهوم پایه‌ای این ساختار آشنا نیستید، مطالعه هوک‌های وردپرس چیستند و چگونه کار می‌کنند نقطه شروع خوبی است. همچنین برای درک چارچوب کلی این مفهوم، می‌توانید نگاهی به تعریف Hooking در برنامه‌نویسی بیندازید.

چرا شناخت هوک‌ها حیاتی است؟

هوک‌ها ستون فقرات معماری وردپرس هستند و نقش آن‌ها در این سیستم، بسیار فراتر از یک قابلیت جانبی است. بدون هوک‌ها، هیچ افزونه‌ای نمی‌توانست بدون دست‌کاری فایل‌های هسته وردپرس به رفتار سایت شکل بدهد و هر آپدیت، همه چیز را از بین می‌برد. هوک‌ها همان مکانیزمی هستند که به وردپرس اجازه داده در ده‌ها سال گذشته، هم‌زمان محبوب بماند و هم منعطف بماند. اگر با مفهوم پایه‌ای آن آشنا نیستید، مطالعه توابع وردپرس چیست و چگونه از آن‌ها استفاده کنیم مبنای خوبی است چون هوک‌ها در واقع نقاط اتصالی هستند که این توابع در آن‌ها اجرا می‌شوند.

در سطح فنی، شناخت هوک‌ها به دلایل زیر حیاتی است. دلیل اول، درک چرخه اجرای وردپرس است که در آن شما می‌بینید کدام مرحله از پردازش درخواست، چه کاری انجام می‌دهد و کجا می‌توانید به‌طور تمیز مداخله کنید. دلیل دوم، توسعه افزونه و قالب است که در آن هر افزونه‌ای که بنویسید، روی چندین هوک سوار می‌شود. دلیل سوم، عیب‌یابی سریع است که در آن با شناخت هوک‌ها می‌توانید بفهمید کدام بخش از کد مسئول یک رفتار غیرمنتظره است.

تجربه‌ای که در پروژه‌های واقعی به آن رسیده‌ام این است: توسعه‌دهندگانی که هوک‌ها را به‌طور عمیق می‌شناسند، کدی بسیار تمیزتر و قابل نگهداری‌تر می‌نویسند چون می‌دانند کجا و چگونه به هسته وردپرس وصل شوند. در مقابل، توسعه‌دهندگانی که هوک‌ها را فقط سطحی می‌شناسند، معمولاً به سراغ راه‌حل‌های زحمت‌آور مثل ویرایش فایل‌های هسته یا استفاده از `$_GET` و `$_POST` مستقیم می‌روند. اگر می‌خواهید درک عمیق‌تری از ساختار هسته داشته باشید، مقاله‌ای که در ساختار هسته وردپرس چگونه کار می‌کند نوشته‌ام به‌طور کامل این لایه را باز می‌کند.

هوک‌ها، سنگ‌بنای معماری وردپرس هستند؛ اگر آن‌ها را نشناسید، هر تغییری در سایت شما شبیه کار روی یک برج بدون نقشه است. وقتی بشناسید، هر تغییر به یک عملیات جراحی دقیق تبدیل می‌شود.

نکته دومی که در اهمیت هوک‌ها باید در نظر گرفت، نقش آن‌ها در استقلال اکوسیستم است. هوک‌ها همان چیزی هستند که باعث شده‌اند وردپرس با داشتن بیش از ۶۰,۰۰۰ افزونه در مخزن رسمی، هم‌چنان قابل نگهداری بماند. بدون هوک‌ها، هر افزونه‌ای که نصب می‌کردید، احتمال تعارض با افزونه دیگر را چندین برابر می‌کرد. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در افزونه وردپرس چیست و چگونه انتخاب کنیم نوشته‌ام نقطه شروع خوبی است.

Action در برابر Filter: تفاوت بنیادی

هوک‌ها در وردپرس به دو دسته اصلی تقسیم می‌شوند: Action (اکشن) و Filter (فیلتر). تفاوت بنیادی این دو، در نوع مداخله‌شان در جریان اجرا است. Action به شما اجازه می‌دهد در یک نقطه مشخص از اجرا، کدی را اضافه کنید و کاری انجام دهید. Filter به شما اجازه می‌دهد یک داده موجود را قبل از استفاده، تغییر دهید و مقدار جدید را برگردانید. اگر با این تفاوت آشنا نیستید، مقاله‌ای که در تفاوت Action و Filter در وردپرس چیست نوشته‌ام این لایه را با مثال‌های عملی باز می‌کند.

در سطح فنی، تفاوت این دو نوع هوک در سه محور اصلی خلاصه می‌شود. محور اول، خروجی تابع است که در Action تابع هیچ مقداری برنمی‌گرداند اما در Filter تابع حتماً باید مقدار را برگرداند. محور دوم، ترتیب اجرا است که Action معمولاً در نقاط مشخصی از چرخه اجرا اجرا می‌شود اما Filter در هر بار عبور داده از یک نقطه. محور سوم، مکان اتصال است که Action با تابع `add_action` و Filter با تابع `add_filter` ثبت می‌شود. اگر می‌خواهید درک عمیق‌تری از این توابع داشته باشید، مقالاتی که در نحوه استفاده از add_action در وردپرس و نحوه استفاده از add_filter در وردپرس نوشته‌ام به‌طور کامل این لایه را باز می‌کنند.

تجربه‌ای که در پروژه‌های واقعی به آن رسیده‌ام این است: در ابتدای کار توسعه، بسیاری از توسعه‌دهندگان تازه‌کار تفاوت این دو را به‌طور دقیق نمی‌دانند و معمولاً از Action به‌جای Filter استفاده می‌کنند یا برعکس. این اشتباه، در پروژه‌های کوچک ممکن است اثری نداشته باشد اما در پروژه‌های بزرگ، به باگ‌های سخت و بی‌سروصدا منجر می‌شود. اگر می‌خواهید درک عمیق‌تری از اشتباهات این حوزه داشته باشید، مقاله‌ای که در اشتباهات رایج هنگام استفاده از هوک‌ها نوشته‌ام به‌طور کامل این لایه را باز می‌کند.

هوک‌های Action مهم و کاربردهای آن‌ها

هوک‌های Action مهم وردپرس، در نقاط مختلف چرخه اجرا و ذخیره‌سازی قرار دارند و هر کدام برای یک هدف مشخص طراحی شده‌اند. در ادامه، مهم‌ترین آن‌ها را با کاربرد عملی و نمونه کد معرفی می‌کنم. اگر می‌خواهید فهرست کاملی از این هوک‌ها را ببینید، مقاله‌ای که در مهم‌ترین Action Hook های وردپرس نوشته‌ام این لایه را با جزئیات بیشتری باز می‌کند.

هوک init — نقطه شروع امن

هوک `init` یکی از مهم‌ترین هوک‌های Action در وردپرس است که پس از بارگذاری هسته و پیش از پردازش درخواست اجرا می‌شود. این هوک، نقطه شروع امن برای ثبت نوع نوشته سفارشی، ثبت دسته‌بندی سفارشی، ثبت شورت‌کد و بسیاری از کارهای دیگر است.

add_action( 'init', function() {
  register_post_type( 'book', array(
    'label' => 'Books',
    'public' => true,
    'supports' => array( 'title', 'editor', 'thumbnail' )
  ) );
} );

کاربرد اصلی این هوک، ثبت ساختارهای سفارشی است که باید در همه صفحات سایت در دسترس باشند. اشتباه رایج این است که توسعه‌دهندگان از `after_setup_theme` برای ثبت نوع نوشته استفاده می‌کنند، در حالی که این هوک فقط برای تنظیمات قالب طراحی شده است.

هوک wp_loaded — پس از بارگذاری کامل

هوک `wp_loaded` پس از بارگذاری کامل تمام اجزای وردپرس اجرا می‌شود و مناسب کارهایی است که به دسترسی به تمام توابع و کلاس‌ها نیاز دارند. کاربرد اصلی این هوک، پردازش فرم‌ها، بررسی وضعیت لاگین کاربر و اجرای منطق کسب‌وکار در سطح درخواست است.

add_action( 'wp_loaded', function() {
  if ( isset( $_POST['my_form'] ) ) {
    // پردازش فرم
  }
} );

هوک save_post — ذخیره نوشته

هوک `save_post` پس از ذخیره هر نوشته یا برگه اجرا می‌شود و یکی از پرکاربردترین هوک‌های Action در پروژه‌های واقعی است. کاربرد اصلی آن، ذخیره داده‌های متا اضافه، اطلاع‌رسانی، به‌روزرسانی کش و ثبت لاگ است.

add_action( 'save_post', function( $post_id ) {
  if ( wp_is_post_autosave( $post_id ) ) return;
  if ( ! current_user_can( 'edit_post', $post_id ) ) return;
  // پردازش داده متا
}, 10, 1 );

نکته مهم درباره این هوک، بررسی autosave و دسترسی کاربر است. بدون این بررسی‌ها، ممکن است داده‌های ناقص ذخیره شوند یا کاربران بدون دسترسی، عملیات حساسی انجام دهند.

هوک wp_head — تزریق به هدر

هوک `wp_head` در بخش `` هر صفحه اجرا می‌شود و برای تزریق کدهای CSS، JavaScript، متا تگ و لینک‌های اضافی کاربرد دارد. مهم‌ترین کاربرد این هوک، تزریق اسکریپت‌های ردیابی، کدهای سئو و استایل‌های سفارشی است.

add_action( 'wp_head', function() {
  echo '<meta name="my-meta" content="my-value">';
} );

هوک wp_footer — تزریق به فوتر

هوک `wp_footer` درست قبل از بسته‌شدن تگ `` اجرا می‌شود و برای تزریق اسکریپت‌هایی که باید در انتهای صفحه بارگذاری شوند، کاربرد دارد. این هوک برای بهینه‌سازی سرعت، مناسب‌تر از `wp_head` است چون اسکریپت‌های انتهای صفحه، رندر اولیه را بلاک نمی‌کنند.

هوک admin_init — راه‌اندازی پنل مدیریت

هوک `admin_init` فقط در پنل مدیریت اجرا می‌شود و برای ثبت صفحه تنظیمات، بررسی دسترسی کاربر در پنل مدیریت و اجرای منطق خاص مدیران کاربرد دارد. این هوک، معمولاً برای ساخت افزونه‌های اداری استفاده می‌شود.

add_action( 'admin_init', function() {
  register_setting( 'my_plugin_options', 'my_setting' );
} );

هوک wp_enqueue_scripts — بارگذاری فایل‌های استاتیک

هوک `wp_enqueue_scripts` مکانیزم رسمی بارگذاری CSS و JavaScript در فرانت‌اند است. مهم‌ترین کاربرد این هوک، بارگذاری فایل‌های استایل و اسکریپت با استفاده از توابع استاندارد `wp_enqueue_style` و `wp_enqueue_script` است که مدیریت وابستگی و نسخه‌بندی را خودکار می‌کند.

add_action( 'wp_enqueue_scripts', function() {
  wp_enqueue_style( 'my-style', plugins_url( 'style.css', __FILE__ ), array(), '1.0.0' );
} );

هوک user_register — ثبت کاربر جدید

هوک `user_register` پس از ثبت کاربر جدید اجرا می‌شود و برای ارسال ایمیل خوش‌آمدگویی، تنظیم متا کاربر جدید یا اتصال به سرویس‌های خارجی کاربرد دارد.

هوک wp_login — ورود کاربر

هوک `wp_login` پس از ورود موفق کاربر اجرا می‌شود و برای ثبت آخرین ورود، اطلاع‌رسانی به مدیر، اجرای منطق امنیتی و به‌روزرسانی آمار کاربرد دارد. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در فعال‌سازی 2FA برای کاربران وردپرس نوشته‌ام نقطه شروع خوبی است.

هوک delete_post — حذف نوشته

هوک `delete_post` پیش از حذف نوشته از پایگاه داده اجرا می‌شود و برای پاک‌سازی داده‌های مرتبط، حذف فایل‌های ضمیمه و ثبت لاگ کاربرد دارد.

هوک switch_theme — تغییر قالب

هوک `switch_theme` هنگام تغییر قالب فعال اجرا می‌شود و برای پاک‌سازی کش، به‌روزرسانی تنظیمات یا اطلاع‌رسانی به مدیر کاربرد دارد.

هوک‌های Filter مهم و کاربردهای آن‌ها

هوک‌های Filter مهم وردپرس، در نقاط مختلف پردازش داده قرار دارند و هر کدام برای تغییر یک داده مشخص استفاده می‌شوند. در ادامه، مهم‌ترین آن‌ها را معرفی می‌کنم. اگر می‌خواهید فهرست کاملی از این هوک‌ها را ببینید، مقاله‌ای که در مهم‌ترین Filter Hook های وردپرس نوشته‌ام این لایه را با جزئیات بیشتری باز می‌کند.

فیلتر the_content — تغییر محتوای نوشته

فیلتر `the_content` یکی از پرکاربردترین فیلترهای وردپرس است که محتوای نوشته را قبل از نمایش تغییر می‌دهد. کاربرد اصلی آن، افزودن محتوای اضافی به انتهای نوشته (مثل جعبه اشتراک‌گذاری)، تغییر ساختار HTML، یا اعمال پردازش‌های سفارشی روی متن است.

add_filter( 'the_content', function( $content ) {
  if ( is_single() ) {
    $content .= '<div class="my-box">متن اضافه</div>';
  }
  return $content;
} );

نکته مهم درباره این فیلتر، محدودکردن تغییرات به صفحات مشخص (مثل `is_single()`) است. بدون این محدودیت، تغییرات در همه صفحات سایت اعمال می‌شود و می‌تواند به نتایج ناخواسته منجر شود.

فیلتر the_title — تغییر عنوان

فیلتر `the_title` عنوان نوشته یا برگه را قبل از نمایش تغییر می‌دهد. کاربرد اصلی آن، افزودن نشانه به عنوان (مثل ستاره برای نوشته‌های ویژه)، حذف بخشی از عنوان یا اعمال فرمت‌دهی خاص است.

فیلتر the_excerpt — تغییر خلاصه

فیلتر `the_excerpt` خلاصه نوشته را قبل از نمایش تغییر می‌دهد. کاربرد اصلی آن، تنظیم طول خلاصه، افزودن متن راهنمای بیشتر یا حذف بخشی از خلاصه است.

add_filter( 'excerpt_length', function( $length ) {
  return 30;
}, 999 );

فیلتر wp_title — تغییر عنوان صفحه

فیلتر `wp_title` تگ عنوان صفحه را قبل از نمایش تغییر می‌دهد. این فیلتر در نسخه‌های اخیر وردپرس کمتر استفاده می‌شود چون سیستم مدیریت عنوان به `add_theme_support( 'title-tag' )` منتقل شده است. اما در قالب‌های قدیمی، همچنان کاربرد دارد.

فیلتر body_class — تغییر کلاس‌های body

فیلتر `body_class` کلاس‌های CSS تگ `` را تغییر می‌دهد. کاربرد اصلی این فیلتر، افزودن کلاس‌های شرطی برای هدف‌گیری صفحه‌های خاص در CSS است.

add_filter( 'body_class', function( $classes ) {
  if ( is_user_logged_in() ) {
    $classes[] = 'user-logged-in';
  }
  return $classes;
} );

فیلتر the_permalink — تغییر لینک نوشته

فیلتر `the_permalink` آدرس نوشته را قبل از نمایش تغییر می‌دهد. کاربرد اصلی آن، ریدایرکت شرطی، افزودن پارامتر به آدرس یا تغییر ساختار لینک است.

فیلتر login_redirect — تغییر مسیر پس از ورود

فیلتر `login_redirect` مسیر هدایت کاربر پس از ورود را تغییر می‌دهد. کاربرد اصلی این فیلتر، هدایت کاربران با نقش خاص به صفحه داشبورد، هدایت مدیران به صفحه مدیریت و هدایت مشتریان به صفحه سفارش‌های خودشان است.

add_filter( 'login_redirect', function( $redirect_to, $request, $user ) {
  if ( isset( $user->roles ) && in_array( 'administrator', $user->roles ) ) {
    return admin_url();
  }
  return home_url( '/my-account/' );
}, 10, 3 );

فیلتر wp_mail — تغییر ایمیل ارسالی

فیلتر `wp_mail` ایمیل ارسالی توسط وردپرس را قبل از ارسال تغییر می‌دهد. کاربرد اصلی آن، تغییر فرستنده، افزودن امضای دیجیتال (DKIM)، تغییر محتوای ایمیل یا مسیر هدایت ایمیل به سرویس خارجی است.

فیلتر upload_mimes — اجازه آپلود فرمت‌های خاص

فیلتر `upload_mimes` فهرست فرمت‌های مجاز آپلود را تغییر می‌دهد. کاربرد اصلی آن، اجازه آپلود فرمت‌های غیراستاندارد مثل SVG یا PDF است. توجه: اجازه آپلود SVG بدون فایل‌های امنیتی، یک ریسک جدی امنیتی محسوب می‌شود.

فیلتر wp_nav_menu_items — تغییر آیتم‌های منو

فیلتر `wp_nav_menu_items` آیتم‌های منوی ناوبری را قبل از نمایش تغییر می‌دهد. کاربرد اصلی آن، افزودن آیتم شرطی (مثل دکمه تماس برای کاربران لاگین‌کرده) یا تغییر آدرس آیتم‌های موجود است.

فیلتر widget_title — تغییر عنوان ویجت

فیلتر `widget_title` عنوان ویجت را قبل از نمایش تغییر می‌دهد. کاربرد اصلی آن، افزودن نشانه، تغییر ساختار یا اعمال تنظیمات شرطی روی عنوان است.

هوک‌ها بر اساس چرخه اجرای وردپرس

برای درک عمیق‌تر هوک‌ها، بهتر است آن‌ها را بر اساس چرخه اجرای وردپرس دسته‌بندی کنیم. در هر درخواست به وردپرس، مجموعه‌ای از هوک‌ها به‌ترتیب خاصی اجرا می‌شوند و آگاهی از این ترتیب، برای اشکال‌زدایی و توسعه ضروری است.

تجربه‌ای که در پروژه‌های واقعی داشته‌ام این است: اکثر باگ‌های عجیب در وردپرس، از اجرای کد در هوک اشتباه ناشی می‌شوند. برای مثال، ثبت نوع نوشته در هوک `init` امن است اما در هوک `after_setup_theme` ممکن است باعث شود که نوع نوشته در پنل مدیریت شناسایی نشود. اگر می‌خواهید درک عمیق‌تری از این ترتیب داشته باشید، مقاله‌ای که در چگونه ترتیب اجرای هوک‌ها را مدیریت کنیم نوشته‌ام نقطه شروع خوبی است.

پارامترها و تعداد آرگومان‌ها

هر هوک در وردپرس ممکن است تعدادی پارامتر دریافت کند که در تابع callback شما در دسترس است. تعداد پارامترهای هر هوک، در مستندات رسمی وردپرس مشخص شده و در تابع `add_action` یا `add_filter` باید تعداد آن‌ها را به‌طور صریح اعلام کنید.

add_action( 'save_post', 'my_function', 10, 3 );

function my_function( $post_id, $post, $update ) {
  // سه پارامتر در دسترس است
}

پارامتر چهارم در `add_action` و `add_filter`، تعداد آرگومان‌هایی است که تابع شما دریافت می‌کند. اگر این عدد را کمتر از تعداد واقعی بگذارید، تابع شما فقط تعداد محدودی پارامتر دریافت می‌کند و ممکن است با خطا مواجه شود. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در چگونه پارامترهای هوک وردپرس را بشناسیم نوشته‌ام به‌طور کامل این لایه را باز می‌کند.

نکته مهم این است که در هوک‌های Filter، همیشه پارامتر اول مقدار قابل تغییر است و سایر پارامترها اطلاعات کمکی هستند. بنابراین تابع شما حتماً باید پارامتر اول را برگرداند. فراموش‌کردن `return` در فیلتر، یکی از رایج‌ترین اشتباهات توسعه‌دهندگان تازه‌کار است.

اولویت اجرا و ترتیب هوک‌ها

اولویت اجرا (Priority)، یک عدد صحیح است که در پارامتر سوم `add_action` یا `add_filter` مشخص می‌شود و تعیین می‌کند که تابع شما در چه ترتیبی نسبت به توابع دیگر اجرا شود. عدد کوچک‌تر، اولویت اجرای بالاتری دارد و زودتر اجرا می‌شود.

add_action( 'init', 'my_first_function', 5 );   // زودتر
add_action( 'init', 'my_second_function', 15 ); // دیرتر

مقدار پیش‌فرض اولویت، عدد ۱۰ است. اگر مقداری برای اولویت تعیین نکنید، تابع شما با سایر توابعی که اولویت پیش‌فرض دارند، به‌ترتیب ثبت اجرا می‌شود. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در Priority در هوک‌های وردپرس چیست نوشته‌ام به‌طور کامل این موضوع را باز می‌کند.

تجربه‌ای که در پروژه‌های واقعی داشته‌ام این است: در پروژه‌هایی که چند افزونه روی یک هوک مشترک کار می‌کنند، اولویت اجرا می‌تواند تعیین‌کننده باشد. برای مثال، اگر دو افزونه روی فیلتر `the_content` کار می‌کنند و یکی از آن‌ها به خروجی دیگری وابسته است، باید با تنظیم اولویت، ترتیب اجرا را تعیین کنید. بدون توجه به اولویت، خروجی ممکن است ناخواسته باشد.

در وردپرس، اولویت اجرای هوک‌ها مثل صف نانوایی است: هرچه عدد کوچک‌تر، جلوتر. اما برخلاف نانوایی، شما می‌توانید با تنظیم درست اولویت، ترتیب نتیجه را به‌طور دقیق کنترل کنید.

حذف هوک و کاربردهای آن

حذف هوک‌ها یکی از قابلیت‌های مهم در وردپرس است که به شما اجازه می‌دهد تابعی که توسط افزونه یا قالب دیگری ثبت شده را حذف کنید. این قابلیت، در پروژه‌هایی که می‌خواهید رفتار افزونه دیگری را تغییر دهید، کاربرد دارد.

remove_action( 'wp_head', 'wp_generator' );
remove_filter( 'the_content', 'my_filter_function', 10 );

نکته مهم درباره حذف هوک، رعایت اولویت و تعداد پارامترهای دقیق است. برای حذف یک هوک، باید همان اولویت و همان تعداد پارامتری را که در زمان ثبت استفاده شده، مشخص کنید. اگر این مقادیر را اشتباه وارد کنید، هوک حذف نمی‌شود و شما فکر می‌کنید که حذف شده است. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقالاتی که در نحوه حذف یک Action Hook در وردپرس نوشته‌ام به‌طور کامل این موضوع را باز می‌کند.

ساخت هوک سفارشی

علاوه بر هوک‌های هسته وردپرس، شما می‌توانید هوک سفارشی برای پروژه‌های خودتان بسازید تا به سایر توسعه‌دهندگان اجازه دهید به کد شما وصل شوند. ساخت هوک سفارشی به شما این امکان را می‌دهد که افزونه یا قالب خود را به‌عنوان یک پلتفرم قابل توسعه طراحی کنید.

// ثبت یک Action سفارشی
do_action( 'my_plugin_before_process', $data );

// ثبت یک Filter سفارشی
$data = apply_filters( 'my_plugin_modify_data', $data );

کاربرد اصلی هوک‌های سفارشی در افزونه‌های تجاری یا سازمانی است که به سایر توسعه‌دهندگان اجازه می‌دهند بدون دست‌کاری کد اصلی افزونه، رفتار آن را تغییر دهند. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقالاتی که در چگونه یک Action سفارشی در وردپرس بسازیم نوشته‌ام نقطه شروع خوبی است.

هوک‌های کلیدی ووکامرس

ووکامرس به‌عنوان محبوب‌ترین افزونه فروشگاهی وردپرس، هوک‌های اختصاصی زیادی دارد که برای سفارشی‌سازی رفتار فروشگاه استفاده می‌شوند. اگر فروشگاه اینترنتی دارید یا توسعه‌دهنده ووکامرس هستید، شناخت این هوک‌ها ضروری است.

تجربه‌ای که در پروژه‌های واقعی داشته‌ام این است: در فروشگاه‌هایی که به سفارشی‌سازی نیاز دارند، شناخت هوک‌های ووکامرس باعث می‌شود بدون دست‌کاری فایل‌های قالب ووکامرس، سفارشی‌سازی‌ها را انجام دهید. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در هوک‌های وردپرس برای ووکامرس نوشته‌ام به‌طور کامل این موضوع را باز می‌کند.

امنیت و هوک‌ها

امنیت و هوک‌ها، موضوعی است که کمتر به آن پرداخته می‌شود اما در پروژه‌های واقعی، اثر مستقیم دارد. هوک‌ها به شما امکان مداخله در جریان اجرا می‌دهند، اما همین امکان، اگر به‌طور نادرست استفاده شود، می‌تواند به یک نقطه ضعف امنیتی تبدیل شود.

سه اصل امنیتی مهم در استفاده از هوک‌ها وجود دارد. اصل اول، اعتبارسنجی داده ورودی است که در آن باید هر داده‌ای که از کاربر دریافت می‌کنید را قبل از پردازش، اعتبارسنجی کنید. اصل دوم، پاک‌سازی داده خروجی است که در آن باید هر داده‌ای که نمایش می‌دهید را با توابعی مثل `esc_html` یا `esc_attr` پاک‌سازی کنید. اصل سوم، بررسی دسترسی کاربر است که در آن باید قبل از اجرای هر عملیات حساس، با `current_user_can` یا مشابه آن، مجوز کاربر را بررسی کنید.

add_action( 'save_post', function( $post_id ) {
  if ( ! isset( $_POST['my_nonce'] ) || ! wp_verify_nonce( $_POST['my_nonce'], 'my_action' ) ) {
    return;
  }
  if ( ! current_user_can( 'edit_post', $post_id ) ) {
    return;
  }
  $data = sanitize_text_field( $_POST['my_data'] );
  update_post_meta( $post_id, 'my_meta', $data );
} );

تجربه‌ای که در پروژه‌های واقعی داشته‌ام این است: در چندین پرونده امنیتی، منشأ نفوذ از یک هوک بدون اعتبارسنجی شروع شده که به مهاجم اجازه داده داده‌ای را در پایگاه داده درج کند. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقالاتی که در هوک‌های وردپرس و افزایش امنیت کد نوشته‌ام نقطه شروع خوبی است.

دیباگ هوک‌ها

دیباگ هوک‌ها، مهارتی است که هر توسعه‌دهنده وردپرس در مرحله‌ای از کار خود به آن نیاز پیدا می‌کند. یکی از بزرگ‌ترین چالش‌ها در پروژه‌های بزرگ، پیدا کردن این است که کدام هوک در کدام اولویت اجرا می‌شود و کدام بخش از کد مسئول یک رفتار غیرمنتظره است.

سه ابزار اصلی برای دیباگ هوک‌ها در وردپرس وجود دارد. ابزار اول، استفاده از تابع `has_action` و `has_filter` است که بررسی می‌کند آیا یک هوک خاص ثبت شده است یا نه. ابزار دوم، استفاده از تابع `current_filter` است که در داخل یک تابع callback، نام هوک فعلی را برمی‌گرداند. ابزار سوم، افزونه‌هایی مثل Query Monitor هستند که نمایش دقیقی از تمام هوک‌ها و ترتیب اجرای آن‌ها ارائه می‌دهند.

add_action( 'wp_footer', function() {
  global $wp_filter;
  echo '<pre>';
  print_r( $wp_filter['wp_footer'] );
  echo '</pre>';
} );

تجربه‌ای که در پروژه‌های واقعی داشته‌ام این است: در پروژه‌هایی که با چند افزونه سنگین کار می‌کنند، نمایش متغیر `$wp_filter` در یک هوک انتهای صفحه، تصویر کاملی از تمام توابع ثبت‌شده روی هر هوک ارائه می‌دهد. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در دیباگ کردن Action و Filter در وردپرس نوشته‌ام به‌طور کامل این موضوع را باز می‌کند.

دیباگ هوک‌ها مثل پیدا کردن سوزن در انبار کاه است، مگر اینکه از قبل بدانید کدام کاه‌ها را باید نگاه کنید. `$wp_filter` همان ذره‌بین است که سوزن را در چند ثانیه نشان می‌دهد.

اشتباهات رایج در استفاده از هوک‌ها

اشتباهات رایج در استفاده از هوک‌ها، یکی از مسائلی است که در پروژه‌های واقعی بارها دیده‌ام و بسیاری از آن‌ها به باگ‌های سخت و بی‌سروصدا منجر می‌شود. در ادامه، به هشت اشتباه رایج اشاره می‌کنم که در پروژه‌های واقعی با آن‌ها مواجه شده‌ام.

• فراموش کردن `return` در فیلتر: اگر تابع شما مقدار را برنگرداند، مقدار `null` جایگزین می‌شود و همه چیز از بین می‌رود. این رایج‌ترین اشتباه توسعه‌دهندگان تازه‌کار است.
• استفاده از Action به‌جای Filter یا برعکس: این اشتباه، معمولاً در پروژه‌های کوچک اثری ندارد اما در پروژه‌های بزرگ به باگ‌های پنهان منجر می‌شود.
• نادیده‌گرفتن اولویت اجرا: اگر ترتیب اجرای هوک‌ها مهم باشد و شما اولویت را تنظیم نکنید، خروجی می‌تواند ناخواسته باشد.
• استفاده از نام تابع عمومی و بدون پیشوند: اگر نام تابع شما با تابع افزونه دیگری یکسان باشد، خطای Fatal رخ می‌دهد.
• عدم بررسی autosave در `save_post`: این اشتباه باعث می‌شود که در هر autosave، متای شما چندین بار ذخیره شود.
• عدم بررسی دسترسی کاربر: بدون بررسی دسترسی، کاربران با نقش پایین می‌توانند عملیات حساسی را انجام دهند که یک ریسک امنیتی جدی است.
• عدم پاک‌سازی داده ورودی: داده‌ای که از کاربر می‌گیرید باید حتماً با توابع پاک‌سازی مناسب (مثل `sanitize_text_field`) پاک شود.
• تعداد اشتباه آرگومان‌ها: اگر تعداد آرگومان‌های `add_action` کمتر از تعداد پارامترهای هوک باشد، تابع شما فقط بخشی از داده را دریافت می‌کند و ممکن است به خطا منجر شود.

اگر می‌خواهید درک عمیق‌تری از این اشتباهات داشته باشید، مقاله‌ای که در اشتباهات رایج هنگام استفاده از هوک‌ها نوشته‌ام به‌طور کامل این موضوع را باز می‌کند. همچنین برای درک اشتباهات سطح پروژه، مقاله‌ای که در راهنمای حرفه‌ای کار با هوک‌های وردپرس نوشته‌ام نقطه شروع خوبی است.

پرسش‌های پرتکرار درباره هوک‌های وردپرس

این بخش را به سؤالاتی اختصاص داده‌ام که بیشتر در جلسه‌های مشاوره تکرار می‌شوند و پاسخ‌شان در تصمیم نهایی وزن زیادی دارد.

تفاوت Action و Filter در وردپرس چیست؟

تفاوت اصلی این است که Action برای انجام یک عمل در نقطه‌ای از اجرا استفاده می‌شود و مقدار برگشتی ندارد، در حالی که Filter برای تغییر یک داده قبل از استفاده است و حتماً باید مقدار را برگرداند. Action با `add_action` و Filter با `add_filter` ثبت می‌شود. اگر می‌خواهید درک عمیق‌تری از این تفاوت داشته باشید، مقاله‌ای که در تفاوت Action و Filter در وردپرس چیست نوشته‌ام نقطه شروع خوبی است.

مهم‌ترین هوک‌های وردپرس کدامند؟

مهم‌ترین هوک‌های وردپرس شامل موارد زیر هستند: `init` (برای ثبت ساختارهای سفارشی)، `wp_loaded` (برای پردازش فرم‌ها)، `save_post` (برای ذخیره متای نوشته)، `wp_head` و `wp_footer` (برای تزریق کد به هدر و فوتر)، `wp_enqueue_scripts` (برای بارگذاری فایل‌های استاتیک)، `admin_init` (برای تنظیمات پنل مدیریت)، `the_content` (برای تغییر محتوای نوشته)، `the_title` (برای تغییر عنوان) و `body_class` (برای تغییر کلاس‌های body).

هوک `init` در وردپرس چه کاری انجام می‌دهد؟

هوک `init` پس از بارگذاری هسته وردپرس و پیش از پردازش درخواست اجرا می‌شود. این هوک، نقطه شروع امن برای ثبت نوع نوشته سفارشی، ثبت دسته‌بندی سفارشی، ثبت شورت‌کد و ثبت سایر ساختارهای سفارشی است. اگر می‌خواهید این هوک را با مثال‌های عملی بیشتری ببینید، مقاله‌ای که در مهم‌ترین Action Hook های وردپرس نوشته‌ام نقطه شروع خوبی است.

چگونه یک هوک را از افزونه دیگری حذف کنم؟

برای حذف یک هوک، باید از تابع `remove_action` یا `remove_filter` استفاده کنید. نکته مهم این است که باید همان نام تابع، همان اولویت و همان تعداد پارامترها را مشخص کنید. اگر یکی از این مقادیر اشتباه باشد، حذف انجام نمی‌شود. مثال: `remove_action( 'wp_head', 'wp_generator' );`. برای جزئیات بیشتر، مقاله‌ای که در نحوه حذف یک Action Hook در وردپرس نوشته‌ام نقطه شروع خوبی است.

اولویت اجرا در هوک‌ها چگونه کار می‌کند؟

اولویت اجرا یک عدد صحیح است که در پارامتر سوم `add_action` یا `add_filter` مشخص می‌شود. عدد کوچک‌تر، اولویت بالاتری دارد و زودتر اجرا می‌شود. مقدار پیش‌فرض ۱۰ است. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در Priority در هوک‌های وردپرس چیست نوشته‌ام نقطه شروع خوبی است.

چگونه یک هوک سفارشی بسازم؟

برای ساخت هوک سفارشی، از تابع `do_action` برای Action و `apply_filters` برای Filter استفاده می‌کنید. سپس در پروژه‌های دیگر، با `add_action` یا `add_filter` به این هوک وصل می‌شوید. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در چگونه یک Action سفارشی در وردپرس بسازیم نوشته‌ام نقطه شروع خوبی است.

هوک `save_post` در وردپرس چه کاری انجام می‌دهد؟

هوک `save_post` پس از ذخیره هر نوشته یا برگه اجرا می‌شود و یکی از پرکاربردترین هوک‌های Action در پروژه‌های واقعی است. کاربرد اصلی آن، ذخیره متای اضافه، اطلاع‌رسانی به سرویس‌های خارجی و به‌روزرسانی کش است. نکته مهم این است که در تابع callback شما باید بررسی کنید که autosave نباشد و کاربر دسترسی معتبری داشته باشد.

چگونه یک هوک را با استفاده از Query Monitor دیباگ کنم؟

افزونه Query Monitor یکی از بهترین ابزارها برای دیباگ هوک‌های وردپرس است. با نصب و فعال‌سازی این افزونه، در پایین هر صفحه یک نوار نمایش داده می‌شود که در بخش Hooks، تمام هوک‌های اجرا شده، ترتیب آن‌ها، مدت زمان اجرا و توابع ثبت‌شده روی هر هوک را نشان می‌دهد. این ابزار به‌ویژه در پروژه‌هایی که با چند افزونه سنگین کار می‌کنند، بسیار مفید است.

آیا هوک‌ها روی سرعت سایت اثر دارند؟

هوک‌ها به‌طور مستقیم اثر محسوسی روی سرعت سایت ندارند اما هر تابعی که روی یک هوک ثبت می‌شود، مقداری از منابع سرور را مصرف می‌کند. اگر تعداد زیادی هوک با توابع سنگین ثبت شده باشد، می‌تواند روی سرعت پنل مدیریت و در موارد نادر روی فرانت‌اند اثر بگذارد. توصیه من این است که هوک‌های غیرضروری را حذف کنید و توابع ثبت‌شده روی هر هوک را سبک نگه دارید.

آیا هوک‌ها روی امنیت سایت اثر دارند؟

هوک‌ها به‌تنهایی امنیت سایت را تأمین نمی‌کنند اما اگر به‌طور نادرست استفاده شوند، می‌توانند به یک نقطه ضعف امنیتی تبدیل شوند. سه اصل امنیتی مهم در استفاده از هوک‌ها وجود دارد: اعتبارسنجی داده ورودی، پاک‌سازی داده خروجی و بررسی دسترسی کاربر. اگر این سه اصل را رعایت کنید، هوک‌ها به ابزاری امن تبدیل می‌شوند.

چند هوک در وردپرس وجود دارد؟

وردپرس در هسته خود بیش از ۳,۰۰۰ هوک ثبت می‌کند و این تعداد در هر نسخه جدید افزایش می‌یابد. علاوه بر این، هر افزونه و قالب نیز می‌تواند هوک‌های سفارشی خود را ثبت کند. در پروژه‌های بزرگ که ده‌ها افزونه فعال است، ممکن است بیش از ۱۰,۰۰۰ هوک در سایت ثبت شده باشد. این تعداد زیاد، دلیل اهمیت شناخت دقیق هوک‌های کلیدی و رعایت اصول استفاده از آن‌هاست.

آیا می‌توانم چند تابع را به یک هوک وصل کنم؟

بله، شما می‌توانید چندین تابع را به یک هوک وصل کنید. با تنظیم اولویت اجرا، ترتیب اجرای این توابع را کنترل می‌کنید. اگر چند تابع روی یک هوک ثبت شده باشند، به‌ترتیب اولویت (از کوچک به بزرگ) و سپس به‌ترتیب ثبت، اجرا می‌شوند.

آیا استفاده از هوک‌ها در قالب توصیه می‌شود؟

بله، استفاده از هوک‌ها در قالب یکی از رویه‌های استاندارد است. به‌جای ویرایش مستقیم فایل‌های قالب، توصیه می‌شود از هوک‌ها برای اضافه‌کردن قابلیت‌های سفارشی استفاده کنید. این رویکرد باعث می‌شود تغییرات شما در آپدیت‌های بعدی قالب از بین نرود. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در هوک‌های وردپرس در توسعه قالب چه کاربردی دارند نوشته‌ام نقطه شروع خوبی است.

چک‌لیست عملی و سخن پایانی

اگر این راهنما را با یک جمله خلاصه کنم، هوک‌ها ستون فقرات معماری وردپرس هستند و شناخت دقیق آن‌ها، تفاوت بین یک توسعه‌دهنده حرفه‌ای و یک توسعه‌دهنده تازه‌کار است. در این راهنما، مهم‌ترین هوک‌های Action و Filter وردپرس را به‌همراه کاربردهای عملی آن‌ها بررسی کردیم و لایه‌های پیشرفته‌تری مثل اولویت اجرا، پارامترها، حذف هوک و ساخت هوک سفارشی را نیز پوشش دادیم.

برای استفاده عملی از این راهنما، چک‌لیست زیر را در پروژه‌های خود اجرا کنید:

• قبل از نوشتن کد، مشخص کنید که از Action استفاده می‌کنید یا Filter.
• هوک مناسب را بر اساس چرخه اجرای وردپرس انتخاب کنید (مثلاً `init` برای ثبت ساختار، `save_post` برای ذخیره داده).
• در فیلترها حتماً مقدار را برگردانید.
• تعداد آرگومان‌ها را با تعداد پارامترهای هوک هم‌راستا کنید.
• اولویت اجرا را در صورت نیاز به‌طور صریح تنظیم کنید.
• در `save_post`، autosave و دسترسی کاربر را بررسی کنید.
• همیشه داده ورودی را اعتبارسنجی و داده خروجی را پاک‌سازی کنید.
• نام توابع را با پیشوند اختصاصی (مثل نام افزونه یا قالب) شروع کنید.
• در صورت نیاز به حذف هوک، اولویت و تعداد پارامترها را دقیق مشخص کنید.
• از افزونه Query Monitor برای دیباگ هوک‌ها استفاده کنید.

اگر تجربه‌ای از کار با هوک‌های وردپرس در پروژه‌های واقعی دارید — چه موفق، چه ناامیدکننده — برایم جالب است که در دیدگاه‌ها بنویسید کدام هوک بیشترین اثر را روی پروژه شما داشته و کدام اشتباه در استفاده از آن‌ها بیشترین زمان را از شما گرفته است. تجربه‌های واقعی شما، این راهنما را برای خواننده بعدی دقیق‌تر و کاربردی‌تر خواهد کرد. 🔗