چرا افزونه شما نقاط توسعه ندارد؟ راهنمای هوک do_action
تابع do_action برای ایجاد نقاط توسعه در قالب و افزونه وردپرس؛ بررسی پارامترها، prefix، مستندسازی و اشتباهات رایج در افزونه‌پذیری حرفه‌ای.
6 دقیقه مطالعه
چرا نقاط توسعه یک اصل معماری هستند؟
در توسعه وردپرس، هیچ پروژه‌ای در جزیره ایزوله زندگی نمی‌کند. سایر افزونه‌ها و توسعه‌دهندگان باید بتوانند کد خود را در نقاط مشخصی از قالب یا افزونه شما تزریق کنند. اگر کد شما این امکان را فراهم نکند، هر افزونه‌ای که بخواهد کد تزریق کند، مجبور است فایل‌های شما را ویرایش کند که در به‌روزرسانی‌ها از بین می‌رود. تابعdo_action() ابزار اصلی وردپرس برای ایجاد این نقاط توسعه است. با استفاده از آن، نقاط مشخصی در جریان اجرای کد شما ایجاد می‌شود که سایر افزونه‌ها می‌توانند به آنها متصل شوند و کد خود را اجرا کنند.
تابع do_action چیست؟
تابعdo_action() یک تابع هسته وردپرس است که در فایل wp-includes/plugin.php تعریف شده است. این تابع تمام callbackهای ثبت‌شده به یک اکشن مشخص را فراخوانی می‌کند.
برخلاف apply_filters که مقدار را عبور می‌دهد و مقدار تغییر‌یافته را برمی‌گرداند، do_action مقدار بازگشتی ندارد. این تابع تنها نقاط اجرا ایجاد می‌کند.
نکته مهم این است که نام اکشن باید یکتا و معنادار باشد تا با اکشن‌های دیگر تداخل نکند.
امضای تابع و پارامترها
امضای این تابع به‌شکل زیر است:function do_action( $hook_name, ...$args ) {
global $wp_filter, $wp_actions, $wp_current_filter;
if ( ! isset( $wp_filter[ $hook_name ] ) ) {
return;
}
$wp_actions[ $hook_name ] = isset( $wp_actions[ $hook_name ] )
? $wp_actions[ $hook_name ] + 1
: 1;
$wp_current_filter[] = $hook_name;
$wp_filter[ $hook_name ]->do_action( $args );
array_pop( $wp_current_filter );
}hook_name) نام اکشن است. پارامترهای بعدی (Variadic) مقادیری هستند که به callbackها پاس داده می‌شوند.
نکته مهم: هرچه تعداد پارامترهای اضافی بیشتر باشد، callbackها باید تعداد بیشتری آرگومان بپذیرند. همیشه در add_action تعداد آرگومان‌ها را درست تعریف کنید.
سازوکار داخلی تابع
تابعdo_action از متغیر جهانی $wp_filter استفاده می‌کند که یک آرایه از تمام اکشن‌ها و فیلترهای ثبت‌شده است.
برای هر اکشن، متد do_action روی شیء WP_Hook تمام callbackها را بر پایه اولویت فراخوانی می‌کند. هر callback می‌تواند ورودی را دریافت کند اما مقدار بازگشتی ندارد.
شمارنده $wp_actions با هر فراخوانی یک واحد افزایش می‌یابد و این ساختار پایه did_action است. نام اکشن هم به پشته $wp_current_filter اضافه می‌شود که پایه doing_action و current_action است.
تفاوت با apply_filters
دو تابع کلیدی در سیستم هوک وردپرس وجود دارد: -do_action: تنها یک نقطه اجرا ایجاد می‌کند و مقدار بازگشتی ندارد
- apply_filters: مقدار را عبور می‌دهد و مقدار تغییر‌یافته را برمی‌گرداند
انتخاب بین این دو به هدف شما بستگی دارد:
- اگر می‌خواهید کد اضافی در نقطه‌ای خاص اجرا شود، از do_action استفاده کنید
- اگر می‌خواهید مقدار قابل تغییر باشد، از apply_filters استفاده کنید
راهنمای تابع دیگر در صفحه apply_filters آمده است.
نام‌گذاری و prefix اکشن‌ها
نام اکشن باید معنادار و یکتا باشد تا با اکشن‌های دیگر تداخل نکند. بهترین رویکرد، استفاده از پیشوند اختصاصی است:do_action( 'mytheme_before_header' );
do_action( 'mytheme_after_header' );
do_action( 'myplugin_before_checkout', $cart );
do_action( 'myplugin_after_order_created', $order_id, $order );header یا footer خودداری کنید
نکته مهم: نام اکشن در مستندات افزونه باید ثبت شود تا سایر توسعه‌دهندگان بتوانند از آن استفاده کنند.
کاربردهای عملی در قالب و افزونه
ایجاد نقاط توسعه در قالب:<header class="site-header">
<?php do_action( 'mytheme_before_header_content' ); ?>
<div class="header-inner">
<?php get_template_part( 'parts/logo' ); ?>
<?php get_template_part( 'parts/nav' ); ?>
</div>
<?php do_action( 'mytheme_after_header_content' ); ?>
</header>do_action( 'myplugin_checkout_before_payment', $cart );
// فرم پرداخت
do_action( 'myplugin_checkout_after_payment', $cart );مستندسازی نقاط توسعه
یکی از اصول حرفه‌ای، مستندسازی اکشن‌ها با استفاده از DocBlock است:/**
* Fires after the header content is rendered.
*
* @since 1.0.0
*
* @param string $layout Current layout context ('default', 'full-width').
*/
do_action( 'mytheme_after_header_content', $layout );@since را برای نسخه‌ای که اکشن اضافه شده ذکر کنید و پارامترها را به‌درستی مستند کنید. برای مطالعه بیشتر روی add_action و نحوه اتصال به این نقاط، به راهنمای add_action مراجعه کنید.
نکات امنیتی و اشتباهات رایج
اشتباه اول، نبود مستندسازی است. اگر اکشن‌ها مستند نشوند، هیچ‌کس نمی‌داند که وجود دارند و چه پارامترهایی می‌پذیرند. اشتباه دوم، نبود prefix است. اکشن‌هایی با نام‌های عمومی مانندbefore_header با اکشن‌های دیگر تداخل می‌کنند.
اشتباه سوم، نبود پارامترهای مناسب است. اگر می‌خواهید callbackها اطلاعاتی دریافت کنند، باید پارامترها را پاس دهید.
اشتباه چهارم، نبود escape در callback است. اگر callback اطلاعاتی را در HTML چاپ می‌کند، باید از توابع escape استفاده کند. راهنمای این تابع در صفحه esc_html آمده است.
اشتباه پنجم، استفاده از do_action برای تغییر مقدار است. برای تغییر مقدار، از apply_filters استفاده کنید.
اشتباه ششم، نبود تست است. باید بررسی کنید که در نبود callback، کد شما به‌درستی کار می‌کند.
اشتباه هفتم، استفاده زیاد از do_action در نقاط غیرضروری است. اضافه کردن نقاط بدون کاربرد مشخص، کد را شلوغ می‌کند.
تحلیل فنی پیشرفته
در نگاه مهندسی، تابعdo_action() یک نقطه معماری در لایه Hook System است که بر چند جنبه از سیستم اثر می‌گذارد. لایه اول لایه Observer Pattern است. callbackهایی که به یک اکشن متصل هستند، ناظرانی هستند که در زمان رخداد اکشن فراخوانی می‌شوند.
لایه دوم لایه Extensibility است. این تابع پایه افزونه‌پذیری وردپرس است. بدون آن، افزونه‌ها نمی‌توانند در نقاط مشخصی از قالب یا افزونه‌های دیگر کد تزریق کنند.
لایه سوم لایه Performance است. اگر اکشن callbackهای سنگین داشته باشد، هر فراخوانی do_action می‌تواند هزینه محسوسی داشته باشد. بنابراین تعریف اکشن در مسیرهای پرتکرار باید با احتیاط انجام شود.
لایه چهارم لایه Naming Contract است. نام اکشن یک قرارداد عمومی است. اگر نام تغییر کند، کدهای وابسته می‌شکنند. بنابراین نام اکشن باید پایدار و معنادار باشد.
لایه پنجم لایه Documentation است. مستندسازی دقیق اکشن‌ها امکان استفاده درست توسط سایر توسعه‌دهندگان را فراهم می‌کند.
لایه ششم لایه Multisite است. در شبکه‌های Multisite، اکشن‌ها در هر سایت مستقل هستند.
لایه هفتم لایه Integration است. ترکیب do_action با add_action، remove_action و has_action یک اکوسیستم کامل از افزونه‌پذیری می‌سازد.
لایه هشتم لایه Testing است. تست‌های واحد باید هم رفتار در نبود callback و هم در حضور callback را بررسی کنند. مفاهیم پایه‌ای Observer Pattern در Observer Pattern در ویکی‌پدیا توضیح داده شده است.
برای مطالعه بیشتر روی توابع مرتبط، می‌توانید به راهنمای add_action، راهنمای apply_filters، راهنمای remove_action، راهنمای has_action، راهنمای did_action، راهنمای doing_action، راهنمای current_action و راهنمای current_filter مراجعه کنید.
پرسش‌های پرتکرار
تفاوتdo_action و apply_filters چیست؟ اولی مقدار برنمی‌گرداند و دومی مقدار را عبور می‌دهد و برمی‌گرداند.
آیا do_action بدون callback کار می‌کند؟ بله، هیچ خطایی نمی‌دهد.
چطور نام اکشن مناسب انتخاب کنیم؟ با prefix اختصاصی و نام معنادار.
آیا باید پارامترها را حتماً مستند کنیم؟ بله، برای اینکه سایر توسعه‌دهندگان بدانند چه پارامترهایی پاس داده می‌شود.
آیا می‌توان همان اکشن را چند بار در چند نقطه فراخوانی کرد؟ بله، اما باید معنادار و پایدار باشد.
نتیجه و مسیر ادامه
تابعdo_action() ابزار اصلی وردپرس برای ایجاد نقاط توسعه در قالب و افزونه است. استفاده درست از آن یعنی تعریف نام معنادار با prefix اختصاصی، مستندسازی دقیق با DocBlock، پاس دادن پارامترهای مناسب و تست در سناریوهای مختلف. اشتباه‌های کوچک در این تابع اغلب به نبود امکان سفارشی‌سازی یا ناسازگاری با افزونه‌های دیگر منجر می‌شوند.
اگر این تابع را در پروژه‌ای واقعی به کار برده‌اید و رفتار غیرمنتظره‌ای دیده‌اید — به‌خصوص در ترکیب با افزونه‌های پیچیده یا در قالب‌های ماژولار — تجربه‌تان می‌تواند راهگشای دیگران باشد. کدام بخش بیشترین زمان را از شما گرفت؟ دیدگاه خود را بنویسید.
سعید کریمه
نویسنده
نویسنده در وردپرس کار.