اکشن‌ها در وردپرس و زمان‌بندی اجرای آن‌ها

در پروژه‌ای که یک سیستم اشتراک محتوای سازمانی را با وردپرس می‌ساختیم، یک باگ عجیب سه هفته تیم را درگیر کرد: داده‌های اضافی کاربران در بعضی از درخواست‌ها ذخیره نمی‌شد و در بعضی دیگر دو بار ذخیره می‌شد. بعد از ساعت‌ها عیب‌یابی، ریشه ماجرا در یک add_action با اولویت اشتباه بود که روی هوک save_post ثبت شده بود و پیش از آماده‌شدن متادیتای فرم اجرا می‌شد. آن سه هفته به من یاد داد که اکشن‌ها (Actions) در وردپرس فقط یک قرارداد ساده نیستند؛ یک زمان‌بندی دقیق است که اگر درست فهمیده نشود، می‌تواند به باگ‌های نامرئی و گریزان منجر شود. در این تحلیل، همان نقشه دقیقی را باز می‌کنم که در پروژه‌های سازمانی برای فهم و کنترل زمان‌بندی اکشن‌های وردپرس به‌کار می‌برم: از چرخه عمر یک درخواست وردپرس (WordPress Request Lifecycle) تا ترتیب اجرای اکشن‌ها در هر مرحله، از هوک‌های کلیدی هر فاز تا تکنیک‌های عیب‌یابی زمان‌بندی، و از اشتباهات رایج در تعیین اولویت تا الگوهای پیشرفته در افزونه‌های سازمانی. اگر با مفهوم کلی اکشن و فیلتر آشنا نیستید، ابتدا تفاوت اکشن و فیلتر در وردپرس را بخوانید تا لایه‌های زیرین این بحث را درک کنید.

اکشن در وردپرس: مکانیزم اجرای عمل در لحظه مشخص

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

مکانیزم ثبت اکشن در وردپرس از طریق تابع add_action() انجام می‌شود که سه پارامتر اصلی می‌گیرد: نام اکشن، نام تابع callback، و اولویت (priority). نام اکشن، نقطه اتصال در هسته است. تابع callback، کدی است که شما می‌خواهید در آن نقطه اجرا شود. و اولویت، عددی است که ترتیب اجرای چند callback متصل به یک اکشن واحد را مشخص می‌کند. مقدار پیش‌فرض اولویت ۱۰ است؛ callbackهایی که اولویت پایین‌تر دارند (مثل ۵) زودتر اجرا می‌شوند و callbackهایی که اولویت بالاتر دارند (مثل ۲۰) دیرتر. برای یادگیری نحوه استفاده صحیح از تابع add_action، نحوه استفاده از add_action در وردپرس را بخوانید.

اکشن، یک قرارداد زمانی است: هسته می‌گوید «من در این لحظه به تو فرصت می‌دهم» — اگر کدت را در لحظه اشتباه وصل کنی، فرصت را از دست داده‌ای، بدون این‌که خطایی ببینی.

چرخه عمر یک درخواست وردپرس: نقشه کلی

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

از منظر معماری، این چرخه را می‌توان به پنج دسته کلی تقسیم کرد. دسته اول، فاز راه‌اندازی (Bootstrap) که در آن، هسته وردپرس، افزونه‌ها و قالب بارگذاری می‌شوند. دسته دوم، فاز مقدارگیری (Initialization) که در آن، نقش کاربر مشخص می‌شود و کوئری اصلی وردپرس آماده می‌شود. دسته سوم، فاز رندر (Rendering) که در آن، قالب انتخاب می‌شود و HTML نهایی تولید می‌شود. دسته چهارم، فاز پیشخوان که چرخه‌ای متفاوت با فرانت‌اند دارد. دسته پنجم، فازهای موازی مثل AJAX، REST API و Cron که مسیرهای جداگانه‌ای را طی می‌کنند. هر کدام از این دسته‌ها، اکشن‌های کلیدی خودشان را دارند و شناخت آن‌ها برای هر توسعه‌دهنده حرفه‌ای ضروری است. برای درک عمیق‌تر معماری هسته وردپرس، ساختار هسته وردپرس چگونه کار می‌کند راهنمای جامعی است.

فاز راه‌اندازی: از wp-settings.php تا muplugins_loaded

فاز راه‌اندازی، اولین فاز چرخه عمر درخواست وردپرس است. در این فاز، هسته وردپرس بارگذاری می‌شود، پیکربندی سایت خوانده می‌شود، افزونه‌ها و قالب‌ها شناسایی می‌شوند، و سیستم هوک‌ها مقدارگیری می‌کند. این فاز، حدود ۲۰ تا ۵۰ میلی‌ثانیه طول می‌کشد اما در سایت‌های با افزونه‌های زیاد، ممکن است به چند صد میلی‌ثانیه برسد. مهم‌ترین اکشن‌های این فاز به ترتیب اجرا عبارتند از: muplugins_loaded، plugins_loaded، sanitize_comment_cookies، و setup_theme. هر کدام از این اکشن‌ها، نقطه‌ای کلیدی برای توسعه‌دهنده است.

اکشن muplugins_loaded، در ابتدای فاز راه‌اندازی اجرا می‌شود و قبل از بارگذاری افزونه‌های معمولی است. این اکشن برای افزونه‌هایی است که نیاز به کنترل کامل روی فرآیند بارگذاری دارند — مثل افزونه‌های Must-Use که در پوشه mu-plugins قرار می‌گیرند. اگر می‌خواهید کدتان قبل از همه افزونه‌های دیگر اجرا شود، این نقطه درست است. اکشن plugins_loaded، بلافاصله پس از بارگذاری همه افزونه‌ها اجرا می‌شود و نقطه اتصال استاندارد برای کدی است که نیاز به تعامل با افزونه‌های دیگر دارد. نکته مهم این است که در این فاز، هنوز نقش کاربر مشخص نشده و کوئری اصلی وردپرس آماده نشده است. اگر کد شما به این دو نیاز دارد، باید از فازهای بعدی استفاده کنید. برای مطالعه بیشتر در مورد ساختار فایل‌های وردپرس، ساختار فایل‌های یک قالب استاندارد وردپرس راهنمای دقیقی است.

فاز مقدارگیری: init، wp_loaded و admin_init

فاز مقدارگیری، دومین مرحله از چرخه عمر درخواست است و در آن، هویت کاربر، کوئری اصلی وردپرس، و وضعیت محیط مشخص می‌شود. این فاز، نقطه اتصال اصلی برای اکثر قابلیت‌های سفارشی است چون در این نقطه، همه چیز برای تصمیم‌گیری آماده است. مهم‌ترین اکشن‌های این فاز به ترتیب اجرا: init، wp_loaded، و در پیشخوان admin_init. اکشن init، پرکاربردترین اکشن وردپرس است. این اکشن، پس از این‌که همه چیز بارگذاری شد اما پیش از ارسال هر خروجی، اجرا می‌شود. اکثر توسعه‌دهندگان، پست تایپ سفارشی، تاکسونومی سفارشی، و قابلیت‌های عمومی را در این نقطه ثبت می‌کنند. اگر با ساختار پست تایپ سفارشی آشنا نیستید، پست تایپ سفارشی CPT را درست پیاده کنید راهنمای جامعی است.

اکشن wp_loaded، پس از init اجرا می‌شود و نقطه آخرین فرصت برای تنظیمات قبل از پردازش کوئری اصلی است. اگر کد شما نیاز به دسترسی به شیء کاربر یا کوئری اصلی دارد، این نقطه مناسب است. اکشن admin_init، فقط در بخش پیشخوان اجرا می‌شود و نقطه اتصال استاندارد برای کدی است که فقط در پنل مدیریت نیاز است — مثل افزودن صفحه تنظیمات، اضافه کردن متاباکس، یا غیرفعال کردن بخشی از پیشخوان. یک نکته مهم در مورد این فاز: init فقط یک بار در هر درخواست اجرا می‌شود، اما admin_init ممکن است در سناریوهای خاص چند بار اجرا شود. برای مطالعه عمیق‌تر زمان‌بندی هوک‌ها در پیشخوان، هوک‌های وردپرس در توسعه قالب چه کاربردی دارند را بخوانید.

// الگوی استاندارد ثبت اکشن‌های فاز مقدارگیری
add_action( 'init', 'wpkar_register_custom_post_types' );
add_action( 'wp_loaded', 'wpkar_check_user_permissions' );
add_action( 'admin_init', 'wpkar_setup_admin_pages' );

فاز رندر: template_redirect، wp_head و wp_footer

فاز رندر، سومین مرحله از چرخه عمر درخواست است و در آن، قالب سایت انتخاب می‌شود و HTML نهایی تولید می‌شود. مهم‌ترین اکشن‌های این فاز به ترتیب اجرا: template_redirect، wp_head، wp_body_open، get_footer، و wp_footer. اکشن template_redirect، نقطه‌ای کلیدی برای کدی است که باید قبل از انتخاب قالب اجرا شود — مثل بررسی دسترسی کاربر، ریدایرکت به صفحه دیگر، یا تنظیم کوکی‌ها. این اکشن، یکی از پرکاربردترین اکشن‌های وردپرس برای پیاده‌سازی منطق شرطی در سطح کل سایت است.

اکشن wp_head، درون تگ <head> اجرا می‌شود و نقطه اتصال استاندارد برای اضافه کردن CSS، متا تگ، یا اسکریپت به بخش هد است. اکثر قالب‌های حرفه‌ای، این اکشن را در فایل header.php فراخوانی می‌کنند. اکشن wp_footer، در انتهای تگ <body> اجرا می‌شود و نقطه اتصال استاندارد برای اضافه کردن اسکریپت‌های عمومی و کدهای تحلیلی است. مهم است بدانید که این اکشن‌ها در هر بار بارگذاری صفحه اجرا می‌شوند و هر callbackی که به آن‌ها متصل است، هزینه‌ای در هر درخواست دارد. اگر callback شما محاسبات سنگین دارد، حتماً نتایج را کش کنید. برای یادگیری استراتژی‌های بهینه‌سازی سرعت، بهترین افزونه‌های کش وردپرس برای افزایش سرعت راهنمای دقیقی است.

فاز رندر، آخرین فرصت برای مداخله در خروجی HTML است — هر اکشنی که در این فاز اجرا می‌شود، مستقیماً روی تجربه کاربر اثر می‌گذارد.

فاز پیشخوان: چرخه متفاوت اکشن‌ها در admin

فاز پیشخوان، از نظر معماری یکی از پیچیده‌ترین فازهای چرخه عمر درخواست است چون چرخه‌ای متفاوت از فرانت‌اند دارد و بعضی اکشن‌ها در ترتیب متفاوتی اجرا می‌شوند. مهم‌ترین اکشن‌های این فاز: admin_init، admin_menu، add_meta_boxes، save_post، admin_enqueue_scripts، admin_head، و admin_footer. اکشن admin_menu، پس از admin_init اجرا می‌شود و نقطه اتصال استاندارد برای اضافه کردن صفحه‌های منو و زیرمنو در پنل مدیریت است. اگر می‌خواهید یک صفحه تنظیمات سفارشی به پیشخوان اضافه کنید، این نقطه درست است.

اکشن add_meta_boxes، پس از admin_menu و پیش از رندر پیشخوان اجرا می‌شود و نقطه اتصال استاندارد برای اضافه کردن متاباکس به صفحه ویرایش نوشته یا هر نوع‌نوشته دیگر است. برای یادگیری نحوه کار با متاباکس، کار با متاباکس‌ها در کدنویسی وردپرس راهنمای دقیقی است. اکشن save_post، پرکاربردترین اکشن در توسعه افزونه‌هایی است که داده سفارشی به نوشته اضافه می‌کنند. این اکشن، در زمان ذخیره نوشته اجرا می‌شود — و در این نقطه، رایج‌ترین باگ‌های زمان‌بندی اتفاق می‌افتد چون بعضی توسعه‌دهندگان متادیتای فرم را قبل از آماده شدن می‌خوانند. توصیه من: همیشه قبل از پردازش، با تابع get_post_type() نوع‌نوشته را بررسی کنید، با wp_verify_nonce() امنیت فرم را تأیید کنید، و با defined( 'DOING_AUTOSAVE' ) اجرا در autosave را غیرفعال کنید.

فاز AJAX و REST API: چرخه‌های موازی

AJAX و REST API، دو مسیر موازی هستند که چرخه عمر متفاوتی از فرانت‌اند و پیشخوان دارند. در درخواست AJAX، وردپرس با فایل admin-ajax.php بارگذاری می‌شود و چرخه‌ای کوتاه‌تر را طی می‌کند. اکشن wp_ajax_{action} برای درخواست‌های کاربران وارد‌شده و wp_ajax_nopriv_{action} برای کاربران مهمان، پرکاربردترین اکشن‌های AJAX هستند. این دو اکشن، نامشان پویا است و به نام عملیاتی که ارسال می‌کنید بستگی دارد. در REST API هم چرخه مشابهی وجود دارد اما با اکشن‌های متفاوت مثل rest_api_init که نقطه اتصال برای ثبت endpointهای سفارشی است.

نکته مهم در فاز AJAX و REST API، این است که بعضی از اکشن‌های فاز راه‌اندازی و مقدارگیری (مثل init و plugins_loaded) در این فازها هم اجرا می‌شوند، اما اکشن‌های فاز رندر (مثل wp_head و wp_footer) هرگز اجرا نمی‌شوند چون خروجی HTML وجود ندارد. اگر کد شما به این اکشن‌ها وابسته است، حتماً بررسی کنید که در فاز AJAX یا REST به‌درستی اجرا شود. یکی از باگ‌های رایج در پروژه‌ها این است که توسعه‌دهنده کدی را به wp_head متصل می‌کند و انتظار دارد در فاز AJAX هم اجرا شود — که هرگز نمی‌شود. برای یادگیری عمیق‌تر REST API در وردپرس، آموزش استفاده از REST API در وردپرس راهنمای جامعی است.

فاز Cron: اکشن‌های زمان‌بندی‌شده بدون درخواست کاربر

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

یک نکته مهم در فاز Cron: در سایت‌های کم‌بازدید، ممکن است cron دیر اجرا شود چون مکانیزم cron وردپرس به بازدید سایت وابسته است. در سایت‌های پربازدید هم اگر cron در حین درخواست کاربر اجرا شود، می‌تواند به کندی و پرش TTFB منجر شود. راه‌حل استاندارد: در محیط تولید، wp-cron را غیرفعال کنید و از cron واقعی سرور (در cPanel یا CLI) استفاده کنید. این کار، هم زمان‌بندی دقیق‌تری می‌دهد و هم بار اضافی از درخواست‌های کاربران را برمی‌دارد. اگر با مشکل کندی سایت در بازه‌های تصادفی روبرو هستید، احتمالاً ریشه در همین موضوع است. برای یادگیری عیب‌یابی این مسئله، رفع مشکلات کرون در وردپرس راهنمای کاملی است.

اولویت و زمان‌بندی: تفاوت‌های ظریف که باگ می‌سازند

اولویت (Priority) در اکشن‌ها، یکی از پرکاربردترین ابزارها برای کنترل زمان‌بندی است. مقدار پیش‌فرض ۱۰ است، اما می‌توانید از اعداد پایین‌تر (مثل ۱ یا ۵) برای اجرای زودتر و از اعداد بالاتر (مثل ۲۰ یا ۱۰۰) برای اجرای دیرتر استفاده کنید. یک نکته ظریف که در پروژه‌های واقعی بارها به آن برخورده‌ام: اگر چند callback با اولویت یکسان به یک اکشن متصل شوند، ترتیب اجرایشان بر اساس ترتیبی است که ثبت شده‌اند. اما این ترتیب، همیشه قابل پیش‌بینی نیست چون افزونه‌ها به ترتیب بارگذاری فایل‌ها ثبت می‌شوند و این ترتیب خودش به فاکتورهایی مثل نام‌گذاری فایل‌ها و ترتیب فعال‌سازی بستگی دارد. برای یادگیری عمیق‌تر این موضوع، Priority در هوک‌های وردپرس چیست راهنمای جامعی است.

توصیه من: همیشه برای callbackهای خودتان اولویت‌های غیرپیش‌فرض استفاده کنید. اگر می‌خواهید زودتر از همه اجرا شوید، اولویت ۱ یا ۵ انتخاب کنید. اگر می‌خواهید بعد از همه اجرا شوید، اولویت ۹۹ یا ۹۹۹ انتخاب کنید. اگر می‌خواهید در میانه اجرا شوید، اولویت‌های میانی مثل ۱۵ یا ۲۰ انتخاب کنید. این رویکرد، از بروز تعارض با افزونه‌های دیگر جلوگیری می‌کند و ترتیب اجرا را قابل پیش‌بینی‌تر می‌کند. یک تکنیک حرفه‌ای در پروژه‌های سازمانی: برای هر افزونه، یک جدول اختصاصی از اولویت‌ها تعریف کنید و در مستندات پروژه ثبت کنید. این جدول، در روزهای عیب‌یابی و در زمان به‌روزرسانی افزونه‌ها نجات‌دهنده است. برای یادگیری استراتژی‌های پیشرفته مدیریت اولویت، چگونه ترتیب اجرای هوک‌ها را مدیریت کنیم را بخوانید.

اکشن‌های کلیدی که هر توسعه‌دهنده باید زمانشان را بداند

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

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

عیب‌یابی زمان‌بندی: چطور ترتیب اجرا را ببینیم؟

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

روش دوم، استفاده از هوک‌های دیباگ سفارشی. می‌توانید با add_action و error_log، ترتیب اجرای اکشن‌های خاص را در فایل لاگ ثبت کنید. این روش، در پروژه‌هایی که Query Monitor نمی‌تواند در آن‌ها نصب شود (مثل محیط تولید) کاربردی است. روش سوم، استفاده از پروفایلرهای PHP مثل Xdebug یا Tideways. این ابزارها، نه‌فقط ترتیب اجرا بلکه زمان دقیق اجرای هر callback و مصرف حافظه آن‌ها را هم نشان می‌دهند. در پروژه‌های سازمانی که بهینه‌سازی سرعت اولویت دارد، این روش ابزار اصلی است. برای یادگیری کامل این فرآیند، دیباگ کردن Action و Filter در وردپرس راهنمای دقیقی است.

// نمونه کد دیباگ زمان‌بندی اکشن‌ها
add_action( 'init', 'wpkar_debug_init_timing', 1 );
function wpkar_debug_init_timing() {
    if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
        error_log( 'WPKar Debug: init fired at priority 1 — ' . microtime( true ) );
    }
}

add_action( 'init', 'wpkar_debug_init_timing_late', 999 );
function wpkar_debug_init_timing_late() {
    if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
        error_log( 'WPKar Debug: init fired at priority 999 — ' . microtime( true ) );
    }
}

ده اشتباه رایج در زمان‌بندی اکشن‌ها

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

• اشتباه اول: استفاده از init برای کارهای پیشخوان. اگر کد شما فقط در پیشخوان نیاز است، از admin_init استفاده کنید نه init. اجرای بی‌دلیل در فرانت‌اند، هزینه اضافه است.
• اشتباه دوم: اتصال به wp_head در فاز AJAX. اکشن‌های فاز رندر در درخواست‌های AJAX و REST API اجرا نمی‌شوند. اگر کد شما در این فازها نیاز است، از اکشن‌های مناسب استفاده کنید.
• اشتباه سوم: فراموش کردن بررسی DOING_AUTOSAVE در save_post. این خطا، داده‌های ناقصی را ذخیره می‌کند که در ادامه پروژه به مشکل تبدیل می‌شوند.
• اشتباه چهارم: عدم تأیید nonce در save_post. بررسی امنیتی، ضروری است — نه اختیاری. بدون آن، فرم‌های شما در معرض حمله CSRF هستند.
• اشتباه پنجم: استفاده از اولویت پیش‌فرض ۱۰ در همه callbackها. اگر دو افزونه اولویت یکسان داشته باشند، ترتیب اجرا قابل پیش‌بینی نیست. همیشه اولویت غیرپیش‌فرض انتخاب کنید.
• اشتباه ششم: اجرای کوئری سنگین در init یا wp_loaded. این اکشن‌ها در هر درخواست اجرا می‌شوند و کوئری سنگین در آن‌ها، TTFB را به‌شدت بالا می‌برد.
• اشتباه هفتم: نبود تست در فازهای مختلف. همیشه کد خود را در فرانت‌اند، پیشخوان، AJAX، REST، و Cron تست کنید. برخی از باگ‌ها فقط در فازهای خاص ظاهر می‌شوند.
• اشتباه هشتم: عدم بررسی is_admin() در کدهایی که نباید در پیشخوان اجرا شوند. این خطای ساده، می‌تواند به رفتار غیرمنتظره در پیشخوان منجر شود.
• اشتباه نهم: استفاده از توابع بی‌نام (anonymous functions). توابع بی‌نام را نمی‌توان با remove_action حذف کرد و در روزهای عیب‌یابی دردسرساز می‌شوند.
• اشتباه دهم: نبود مستندسازی اولویت‌ها. اگر تیم شما بزرگ است، نبود مستندسازی اولویت‌ها، به آشوب جدی منجر می‌شود. جدول اولویت‌ها را در مستندات پروژه نگه دارید.

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

پرسش‌های پرتکرار درباره اکشن‌ها و زمان‌بندی اجرای آن‌ها

اکشن در وردپرس دقیقاً چیست و چه تفاوتی با فیلتر دارد؟

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

چرا زمان‌بندی اکشن‌ها این‌قدر مهم است؟

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

چرخه عمر یک درخواست وردپرس از چند فاز تشکیل شده است؟

از پنج فاز اصلی: فاز راه‌اندازی (Bootstrap)، فاز مقدارگیری (Initialization)، فاز رندر (Rendering)، فاز پیشخوان، و فازهای موازی مثل AJAX، REST API و Cron. هر فاز، مجموعه‌ای از اکشن‌های کلیدی دارد که در ترتیب مشخصی اجرا می‌شوند.

اکشن init چه زمانی اجرا می‌شود و چرا مهم است؟

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

تفاوت plugins_loaded و init چیست؟

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

چرا کد من در فاز AJAX اجرا نمی‌شود؟

احتمالاً کد شما به اکشن‌های فاز رندر مثل wp_head یا wp_footer متصل است که در درخواست‌های AJAX اجرا نمی‌شوند. برای فاز AJAX از اکشن‌های wp_ajax_{action} یا wp_ajax_nopriv_{action} استفاده کنید. این اکشن‌ها در فایل admin-ajax.php اجرا می‌شوند.

چطور بفهمم چرا کد من در save_post دوبار اجرا می‌شود؟

دلیل رایج، اجرای autosave است. وردپرس هنگام ویرایش طولانی، هر چند دقیقه یک autosave انجام می‌دهد که اکشن save_post را نیز فعال می‌کند. راه‌حل: در ابتدای callback، با شرط if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) { return; } این حالت را نادیده بگیرید. دلیل دوم، ذخیره revision است که با شرط wp_is_post_revision قابل تشخیص است.

چطور ترتیب اجرای اکشن‌ها را تغییر دهم؟

با پارامتر اولویت در تابع add_action. مقدار پیش‌فرض ۱۰ است؛ مقادیر پایین‌تر (مثل ۵) زودتر و مقادیر بالاتر (مثل ۲۰) دیرتر اجرا می‌شوند. اگر می‌خواهید callback شما پس از همه اجرا شود، از اولویت ۹۹۹ یا بالاتر استفاده کنید.

چرا در بعضی سایت‌ها cron وردپرس دیر اجرا می‌شود؟

مکانیزم wp-cron وردپرس، به بازدید سایت وابسته است. در سایت‌های کم‌بازدید، cron دیر اجرا می‌شود چون ممکن است ساعت‌ها بین دو بازدید فاصله باشد. راه‌حل: در محیط تولید، wp-cron را غیرفعال کنید و از cron واقعی سرور (در cPanel یا CLI) استفاده کنید. این کار، زمان‌بندی دقیق‌تری می‌دهد.

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

سه راه‌حل اصلی: اول، نتایج محاسبات سنگین را در Object Cache ذخیره کنید و در بارهای بعد از کش بخوانید. دوم، شرطی کردن اجرا را جدی بگیرید — اگر callback فقط در شرایط خاص نیاز است، ابتدای آن شرط بررسی کنید و در صورت نبود، سریع return کنید. سوم، اکشن‌های سنگین را به cron منتقل کنید و از فاز درخواست کاربر خارج کنید.

تفاوت add_action و add_filter در چیست؟

هر دو توابع ثبت هوک هستند اما برای دو نوع مختلف هوک استفاده می‌شوند. add_action برای اتصال به اکشن‌ها استفاده می‌شود (اجرای عمل، بدون return)، و add_filter برای اتصال به فیلترها (تغییر داده، با return). اگر تابع شما مقداری را برمی‌گرداند، احتمالاً باید از add_filter استفاده کنید.

چطور کد خود را در فاز مناسب از چرخه قرار دهم؟

پاسخ در سه پرسش نهفته است. اول: آیا کد شما نیاز به دسترسی به نقش کاربر دارد؟ اگر بله، از init یا بعد استفاده کنید. دوم: آیا کد شما فقط در پیشخوان نیاز است؟ اگر بله، از admin_init استفاده کنید. سوم: آیا کد شما خروجی HTML تولید می‌کند؟ اگر بله، از فاز رندر مثل wp_head یا wp_footer استفاده کنید. با این سه پرسش، اکثر موارد حل می‌شود.

آیا اکشن‌ها روی سرعت سایت اثر می‌گذارند؟

اکشن‌ها ذاتاً سبک هستند، اما هر callback در هر بار اجرا یک هزینه پردازشی دارد. اگر callback شما کوئری سنگین، فراخوانی API خارجی، یا محاسبات پیچیده دارد، این هزینه در هر بار بارگذاری صفحه پرداخت می‌شود. راه‌حل: کش، شرطی کردن اجرا، و انتقال کارهای سنگین به cron.

زمان‌بندی اکشن‌ها: مهارت نامرئی توسعه حرفه‌ای

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

سه نکته عملی که در پروژه‌های واقعی بیشترین اثر را داشته‌اند. اول، قبل از نوشتن هر کد، یک بار چرخه عمر درخواست را روی کاغذ بکشید و مشخص کنید کد شما در کدام فاز اجرا می‌شود. این تمرین ساده، جلوی نصف اشتباهات زمان‌بندی را می‌گیرد. دوم، همیشه اولویت‌های غیرپیش‌فرض انتخاب کنید و در پروژه‌های تیمی، جدول اولویت‌ها را در مستندات نگه دارید. سوم، کد خود را در همه فازها تست کنید — فرانت‌اند، پیشخوان، AJAX، REST، و Cron. باگ‌های زمان‌بندی، اغلب در فازهایی که فراموش کرده‌اید ظاهر می‌شوند.

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