فهرست هوک‌های WordPress

فهرستی جستجوپذیر از اکشن‌ها و فیلترهای WordPress که توسعه‌دهندگان واقعاً به کار می‌برند — همراه با امضای دقیقِ add_action/add_filter، زمان اجرا، یک مثال کارآمد و همان چیزی که کاربران را غافلگیر می‌کند.

39 هوک، به‌همراه امضای دقیق add_action / add_filter، زمان اجرا شدنشان، یک مثال کاربردی، و آن نکته‌ای که همه را غافلگیر می‌کند. 1 مورد به‌عنوان تأییدنشده علامت خورده‌اند — تعداد آرگومان‌هایشان را در برابر سورس WordPress بررسی نکرده‌ایم و ترجیح می‌دهیم این را علامت بزنیم تا اینکه یک حدس را به‌جای واقعیت جا بزنیم.

این فهرست جامع نیست و ادعایش را هم ندارد — WordPress هزاران هوک دارد. اینجا فقط آن‌هایی پوشش داده شده‌اند که مردم واقعاً سراغشان می‌روند.

39 از 39

پس از پایانِ بارگذاریِ WordPress اما پیش از ارسالِ هر سرآیندی (header) اجرا می‌شود. جای استاندارد برای ثبتِ انواع نوشتهٔ سفارشی، طبقه‌بندی‌ها (taxonomy) و قواعد بازنویسی (rewrite rules).

زمان اجرا

در هر درخواست، هم سمت کاربر و هم پیشخوان، پس از بارگذاریِ هستهٔ اصلی، افزونه‌ها و پوسته.

امضا

add_action( 'init', 'my_callback' );

مثال

add_action( 'init', function () {
    register_post_type( 'book', array(
        'public'       => true,
        'label'        => 'Books',
        'show_in_rest' => true, // required for the block editor
    ) );
} );

نکتهٔ غافلگیرکننده

init در هر درخواستی اجرا می‌شود، از جمله AJAX، REST و cron. انجام هر کارِ کندی در اینجا (یک درخواست HTTP یا یک پرس‌وجوی سنگین) به هر بار بارگذاریِ صفحه فشار می‌آورد. ضمناً: کاربر جاری در اینجا در دسترس است، اما نمی‌توانید چیزی خروجی بدهید — سرآیندها هنوز ارسال نشده‌اند، ولی درست در آستانهٔ ارسال‌اند.

به‌محضِ بارگذاریِ پوسته اجرا می‌شود. جای درست برای add_theme_support()، add_image_size() و ثبتِ منوهای ناوبری.

زمان اجرا

پس از بارگذاریِ functions.php پوسته، پیش از init.

امضا

add_action( 'after_setup_theme', 'my_callback' );

مثال

add_action( 'after_setup_theme', function () {
    add_theme_support( 'post-thumbnails' );
    add_theme_support( 'title-tag' );
    add_image_size( 'card', 600, 400, true ); // true = hard crop
} );

نکتهٔ غافلگیرکننده

ثبت اندازه‌های تصویر روی init به‌جای اینجا در بیشتر موارد اتفاقی کار می‌کند و بعد در برخی موارد به‌طور مرموزی از کار می‌افتد. از after_setup_theme استفاده کنید — این هوک دقیقاً برای همین است.

به‌محضِ بارگذاریِ همهٔ افزونه‌های فعال اجرا می‌شود. زودترین نقطهٔ امن برای تعامل با یک افزونهٔ دیگر.

زمان اجرا

پس از فراخوانیِ همهٔ فایل‌های افزونه، پیش از بارگذاریِ پوسته.

امضا

add_action( 'plugins_loaded', 'my_callback' );

نکتهٔ غافلگیرکننده

کاربر جاری هنوز در اینجا در دسترس نیست — wp_get_current_user() به‌طور قابل‌اتکا کار نمی‌کند. اگر به کاربر نیاز دارید، از init استفاده کنید.

پس از بارگذاریِ کاملِ WordPress اجرا می‌شود — افزونه‌ها، پوسته، init و کاربر همه آماده‌اند.

زمان اجرا

پس از init و پس از راه‌اندازیِ کاربر جاری.

امضا

add_action( 'wp_loaded', 'my_callback' );

در آغازِ هر درخواستِ پیشخوان اجرا می‌شود. برای register_setting()، بررسیِ دسترسی‌ها و تغییرمسیرهای پیشخوان به کار می‌رود.

زمان اجرا

در هر درخواستِ سمتِ پیشخوان.

امضا

add_action( 'admin_init', 'my_callback' );

نکتهٔ غافلگیرکننده

این هوک روی درخواست‌های admin-ajax.php هم اجرا می‌شود، که واقعاً «صفحهٔ پیشخوان» نیستند. اگر کال‌بک شما فرض می‌کند صفحه‌ای وجود دارد، آن را با wp_doing_ajax() محافظت کنید.

تنها جای درست برای بارگذاری (enqueue) CSS و JavaScript سمتِ کاربر.

زمان اجرا

هنگام بارگذاریِ صفحاتِ سمتِ کاربر، پیش از رندر شدنِ سربخش (head).

امضا

add_action( 'wp_enqueue_scripts', 'my_callback' );

مثال

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'child-style',
        get_stylesheet_uri(),
        array( 'parent-style' ),          // load AFTER the parent
        wp_get_theme()->get( 'Version' )  // cache-bust on version change
    );
} );

نکتهٔ غافلگیرکننده

برخلافِ نامش، این هوک علاوه بر اسکریپت‌ها، استایل‌ها را هم مدیریت می‌کند — هیچ هوکی به نامِ wp_enqueue_styles وجود ندارد و کاربران وقتِ واقعی‌شان را صرفِ گشتن دنبالِ آن می‌کنند. ضمناً: این هوک در پیشخوان اجرا نمی‌شود (از admin_enqueue_scripts استفاده کنید) و در ویرایشگر بلوک هم اجرا نمی‌شود (از enqueue_block_editor_assets استفاده کنید).

بارگذاری CSS/JS در پیشخوان. پسوندِ هوکِ صفحهٔ جاری را دریافت می‌کند تا بتوانید دارایی‌ها را فقط روی یک صفحه بارگذاری کنید.

زمان اجرا

هنگام بارگذاریِ صفحاتِ پیشخوان.

امضا

add_action( 'admin_enqueue_scripts', 'my_callback' ); // receives $hook_suffix

مثال

add_action( 'admin_enqueue_scripts', function ( $hook ) {
    if ( 'settings_page_my-plugin' !== $hook ) {
        return; // do not load our JS on every admin screen
    }
    wp_enqueue_script( 'my-admin', plugins_url( 'admin.js', __FILE__ ), array(), '1.0', true );
} );

نکتهٔ غافلگیرکننده

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

بارگذاری دارایی‌ها فقط در ویرایشگر بلوک (Gutenberg) — نه سمت کاربر، نه بقیهٔ پیشخوان.

زمان اجرا

هنگام بارگذاریِ ویرایشگر بلوک.

امضا

add_action( 'enqueue_block_editor_assets', 'my_callback' );

خروجی را درونِ <head> چاپ می‌کند. برای متاتگ‌ها و CSS بحرانیِ درون‌خطی به کار می‌رود.

زمان اجرا

درونِ <head>، سمت کاربر.

امضا

add_action( 'wp_head', 'my_callback' );

نکتهٔ غافلگیرکننده

اسکریپت‌ها یا استایل‌ها را اینجا enqueue نکنید — از wp_enqueue_scripts استفاده کنید که به WordPress اجازه می‌دهد وابستگی‌ها و حذفِ موارد تکراری را مدیریت کند. echo کردنِ یک تگِ <script> درونِ wp_head همهٔ این‌ها را دور می‌زند و دلیلِ این است که این‌همه سایت jQuery را سه بار بارگذاری می‌کنند.

خروجی را درست پیش از </body> چاپ می‌کند. جای درست برای قطعه‌کدهای آنالیتیکس و نشانه‌گذاریِ به‌تعویق‌افتاده (deferred).

زمان اجرا

در انتهای صفحهٔ سمتِ کاربر.

امضا

add_action( 'wp_footer', 'my_callback' );

نکتهٔ غافلگیرکننده

پوسته‌ای که فراخوانیِ wp_footer() را فراموش کند، نوار مدیریت را خراب می‌کند، هر افزونه‌ای را که اسکریپتی در پابرگ enqueue کند می‌شکند و در بازبینیِ پوستهٔ wordpress.org به‌طور خودکار رد می‌شود.

محتوای نوشته را بلافاصله پیش از نمایش فیلتر می‌کند. جای معمول برای افزودنِ نشانه‌گذاری به ابتدا یا انتهای یک نوشته.

زمان اجرا

هر بار که the_content() فراخوانی می‌شود.

امضا

add_filter( 'the_content', 'my_callback' ); // receives $content

مثال

add_filter( 'the_content', function ( $content ) {
    if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
        return $content; // <- the guard everyone forgets
    }
    return $content . '<p class="cta">Enjoyed this? Read more.</p>';
} );

نکتهٔ غافلگیرکننده

این هوک بسیار بیشتر از آنچه فکر می‌کنید اجرا می‌شود — در ابزارک‌ها، در پاسخ‌های REST، در تولیدِ چکیده توسطِ برخی افزونه‌ها و یک بار برای هر نوشته در یک حلقه روی آرشیو. بدونِ محافظِ is_singular / in_the_loop / is_main_query، فراخوانِ عملِ شما پانزده بار روی فهرستِ وبلاگ و داخلِ خوراکِ RSS ظاهر می‌شود. این پُراستفاده‌ترین فیلتری است که در WordPress به‌غلط به کار می‌رود.

عنوانِ نوشته را پیش از نمایش فیلتر می‌کند.

زمان اجرا

هر بار که the_title() یا get_the_title() فراخوانی می‌شود.

امضا

add_filter( 'the_title', 'my_callback', 10, 2 ); // receives $title, $post_id

نکتهٔ غافلگیرکننده

این هوک برای عنوان‌های داخلِ منوی پیشخوان، منوهای ناوبری و عنوانِ سند (<title>) هم اجرا می‌شود. فیلترکردنِ بی‌قیدوشرطِ آن، چیزها را در جاهایی که قصدش را نداشتید تغییرنام می‌دهد.

تعیین می‌کند یک چکیدهٔ خودکار چند کلمه داشته باشد. مقدار پیش‌فرض 55 است.

زمان اجرا

وقتی WordPress برای نوشته‌ای که چکیدهٔ دستی ندارد، چکیده تولید می‌کند.

امضا

add_filter( 'excerpt_length', 'my_callback' ); // receives $length (words)

مثال

add_filter( 'excerpt_length', function ( $length ) {
    return 25;
}, 999 ); // high priority: many themes set this too, and last one wins

نکتهٔ غافلگیرکننده

روی نوشته‌هایی که چکیدهٔ دستی دارند هیچ اثری ندارد — آن‌ها عیناً استفاده می‌شوند. و بسیاری از پوسته‌ها خودشان این فیلتر را تنظیم می‌کنند، پس اغلب برای برنده‌شدن به یک عددِ اولویتِ بالا نیاز دارید.

رشته‌ای را که به انتهای یک چکیدهٔ کوتاه‌شده افزوده می‌شود تغییر می‌دهد. مقدار پیش‌فرض " […]" است.

زمان اجرا

وقتی یک چکیدهٔ خودکار کوتاه (truncate) می‌شود.

امضا

add_filter( 'excerpt_more', 'my_callback' ); // receives $more

یک پرس‌وجو را پیش از اجرا تغییر می‌دهد. راهِ درست برای تغییر آنچه در یک آرشیو نمایش داده می‌شود — به‌مراتب بهتر از یک WP_Query دوم.

زمان اجرا

پس از تجزیهٔ متغیرهای پرس‌وجو، پیش از ساخته‌شدنِ SQL.

امضا

add_action( 'pre_get_posts', 'my_callback' ); // receives WP_Query $query (by reference)

مثال

add_action( 'pre_get_posts', function ( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return; // <- both guards are mandatory
    }
    if ( $query->is_category() ) {
        $query->set( 'posts_per_page', 12 );
    }
} );

نکتهٔ غافلگیرکننده

این هوک در پیشخوان هم اجرا می‌شود و برای هر پرس‌وجو اجرا می‌شود، از جمله منوها، ابزارک‌ها و کتابخانهٔ رسانه. محافظ‌های is_admin() و is_main_query() را حذف کنید و بی‌سروصدا آنچه فهرستِ نوشته‌های پیشخوان نشان می‌دهد را تغییر خواهید داد — باگی که ردیابی‌اش واقعاً دشوار است. همچنین توجه کنید: $query را تغییر دهید، چیزی return نکنید.

عبارتِ خامِ WHERE در SQL یک پرس‌وجو را فیلتر می‌کند.

زمان اجرا

هنگام مونتاژِ SQL پرس‌وجو.

امضا

add_filter( 'posts_where', 'my_callback', 10, 2 ); // receives $where, WP_Query $query

نکتهٔ غافلگیرکننده

شما در حال نوشتنِ SQL خام هستید. همیشه با $query->is_main_query() محافظت کنید و همیشه برای هر ورودیِ کاربر از $wpdb->prepare() استفاده کنید. این سریع‌ترین راه برای وارد کردنِ تزریق SQL به یک سایت WordPress است.

تعداد کلِ نوشته‌هایی را که یک پرس‌وجو یافته فیلتر می‌کند — همان چیزی که صفحه‌بندی از رویش محاسبه می‌شود.

زمان اجرا

پس از اجرای پرس‌وجو، پیش از محاسبهٔ صفحه‌بندی.

امضا

add_filter( 'found_posts', 'my_callback', 10, 2 ); // receives $found_posts, WP_Query $query

اندازهٔ پیکسلی‌ای را تعیین می‌کند که بالاتر از آن WordPress یک بارگذاری را کوچک می‌کند و به‌جای اصلِ شما یک نسخهٔ «-scaled» را ارائه می‌دهد. پیش‌فرض 2560.

زمان اجرا

هنگام بارگذاری، وقتی WordPress تصمیم می‌گیرد که آیا یک تصویر «بزرگ» است.

امضا

add_filter( 'big_image_size_threshold', 'my_callback' ); // receives int $threshold

مثال

// Serve originals at full resolution — no -scaled copy.
add_filter( 'big_image_size_threshold', '__return_false' );

// Or just raise the ceiling:
add_filter( 'big_image_size_threshold', function () {
    return 3840;
} );

نکتهٔ غافلگیرکننده

این تنها رایج‌ترین علتِ «تصویرم بعد از بارگذاری در WordPress تار به نظر می‌رسد» است و تقریباً هیچ‌کس نمی‌داند وجود دارد. اصلِ شما هنوز روی دیسک هست — فقط هرگز ارائه نمی‌شود. توجه کنید که به بلندترین ضلع اعمال می‌شود و فقط بر تصاویری اثر می‌گذارد که پس از فعال‌شدنِ فیلتر بارگذاری شوند.

آرایهٔ اندازه‌های تصویری را که WordPress در آستانهٔ تولیدشان برای یک بارگذاری است فیلتر می‌کند. برای متوقف‌کردنِ تولیدِ یک اندازه، آن را unset کنید.

زمان اجرا

هنگام بارگذاری، پیش از ساخته‌شدنِ فایل‌های مشتق.

امضا

add_filter( 'intermediate_image_sizes_advanced', 'my_callback', 10, 2 ); // receives $sizes, $metadata

مثال

add_filter( 'intermediate_image_sizes_advanced', function ( $sizes ) {
    unset( $sizes['1536x1536'] );
    unset( $sizes['2048x2048'] );
    return $sizes;
} );

نکتهٔ غافلگیرکننده

حذفِ اندازه‌ای که پوستهٔ شما واقعاً از آن استفاده می‌کند یعنی WordPress به اصلِ تمام‌اندازه پناه می‌برد — که بدتر از فضای دیسکی است که ذخیره کردید. و این فقط جلوی ساختِ فایل‌های جدید را می‌گیرد؛ فایل‌های موجود تا وقتی بازتولید (regenerate) نکنید باقی می‌مانند.

کیفیت JPEG را که WordPress تصاویر بارگذاری‌شده را با آن دوباره کدگذاری می‌کند تعیین می‌کند. پیش‌فرض 82.

زمان اجرا

هر وقت WordPress یک JPEG می‌نویسد.

امضا

add_filter( 'jpeg_quality', 'my_callback', 10, 2 ); // receives $quality, $context

نکتهٔ غافلگیرکننده

کیفیت 82 برای عکس‌ها خوب است و برای اسکرین‌شات‌ها، لوگوها و گرافیک‌های تخت به‌وضوح ضعیف است — این‌ها لبه‌های تیز دارند و هیچ نویزِ عکاسی‌ای ندارند که آرتیفکت‌ها را در آن پنهان کنند. ضمناً: wp_editor_set_quality فیلترِ مدرن‌تری است و مستقیماً کلاس‌های ویرایشگر تصویر را پوشش می‌دهد؛ تنظیمِ هر دو رایج است.

کیفیت خروجیِ مورد استفادهٔ کلاس‌های WP_Image_Editor (GD و Imagick) را تعیین می‌کند.

زمان اجرا

وقتی یک نمونه از ویرایشگر تصویر کیفیتش را تنظیم می‌کند.

امضا

add_filter( 'wp_editor_set_quality', 'my_callback', 10, 2 ); // receives $quality, $mime_type

اندازه‌های تصویرِ سفارشیِ شما را به فهرست کشوییِ اندازه در پنجرهٔ رسانه و ویرایشگر بلوک اضافه می‌کند.

زمان اجرا

وقتی رابط کاربریِ رسانه، انتخابگرِ اندازه‌اش را می‌سازد.

امضا

add_filter( 'image_size_names_choose', 'my_callback' ); // receives $sizes

مثال

add_filter( 'image_size_names_choose', function ( $sizes ) {
    return array_merge( $sizes, array( 'card' => __( 'Card', 'textdomain' ) ) );
} );

نکتهٔ غافلگیرکننده

add_image_size() اندازه را ثبت می‌کند اما آن را در ویرایشگر قابل‌انتخاب نمی‌کند. هر پرسشِ «اندازهٔ تصویرِ سفارشی‌ام در فهرست کشویی ظاهر نمی‌شود» به‌خاطر نبودِ همین فیلتر است.

یک فایل را پیش از انتقال به پوشهٔ بارگذاری‌ها بازرسی یا رد می‌کند.

زمان اجرا

حین بارگذاری، پیش از نوشته‌شدنِ فایل.

امضا

add_filter( 'wp_handle_upload_prefilter', 'my_callback' ); // receives $file

نکتهٔ غافلگیرکننده

برای رد یک فایل، $file['error'] را به یک رشتهٔ پیام تنظیم کنید و $file را return کنید. return کردنِ false یا throw کردن، کاری که می‌خواهید را انجام نمی‌دهد.

آرایهٔ فراداده (شامل اندازه‌های تولیدشده) را پس از پردازشِ یک پیوست فیلتر می‌کند.

زمان اجرا

پس از ساخته‌شدنِ تصاویرِ مشتق هنگام بارگذاری.

امضا

add_filter( 'wp_generate_attachment_metadata', 'my_callback', 10, 2 ); // receives $metadata, $attachment_id

نکتهٔ غافلگیرکننده

این همان هوکی است که افزونه‌های بهینه‌سازی تصویر از آن استفاده می‌کنند. می‌تواند کند باشد — پس از نوشته‌شدنِ هر اندازهٔ تصویر اجرا می‌شود و انجامِ یک درخواستِ HTTP در اینجا هر بارگذاری را منتظرش نگه می‌دارد.

نامزدهای srcset را که WordPress برای یک تصویرِ واکنش‌گرا تولید می‌کند فیلتر می‌کند.

زمان اجرا

وقتی یک تصویرِ واکنش‌گرا رندر می‌شود.

امضا

add_filter( 'wp_calculate_image_srcset', 'my_callback', 10, 5 );

نکتهٔ غافلگیرکننده

حذفِ اندازهٔ medium_large (768w) در جای دیگر، بی‌سروصدا srcset را تضعیف می‌کند — این اندازه تقریباً به‌طور کامل برای همین منظور وجود دارد.

تعداد دقیق آرگومان‌های این هوک را در برابر سورس WordPress تأیید نکرده‌ایم. پیش از آنکه به آن تکیه کنید، developer.wordpress.org را بررسی کنید. ترجیح می‌دهیم این نااطمینانی را علامت بزنیم تا اینکه بی‌سروصدا یک حدس را به‌جای واقعیت جا بزنیم.

صفحاتِ منو و زیرمنوی پیشخوان را ثبت می‌کند.

زمان اجرا

وقتی منوی پیشخوان در حال ساخته‌شدن است.

امضا

add_action( 'admin_menu', 'my_callback' );

مثال

add_action( 'admin_menu', function () {
    add_options_page(
        'My Plugin',
        'My Plugin',
        'manage_options',   // capability — NOT a role
        'my-plugin',
        'my_render_settings_page'
    );
} );

نکتهٔ غافلگیرکننده

آرگومانِ قابلیت (capability) یک قابلیت است، نه یک نقش. پاس‌دادنِ «administrator» به‌ظاهر کار می‌کند (چون در برخی پیکربندی‌ها مدیران قابلیتی با همین نام دارند) و بعد بی‌سروصدا به افرادِ نادرست دسترسی می‌دهد. از manage_options استفاده کنید.

یک اعلان در بالای صفحهٔ پیشخوان چاپ می‌کند.

زمان اجرا

هنگام رندرِ صفحهٔ پیشخوان.

امضا

add_action( 'admin_notices', 'my_callback' );

نکتهٔ غافلگیرکننده

روی هر صفحهٔ پیشخوان اجرا می‌شود. افزونه‌ای که روی همهٔ آن‌ها یک اعلانِ بی‌قیدوشرطِ «از نصب متشکریم!» نشان می‌دهد، منفورترین الگو در پیشخوانِ WordPress است. آن را محافظت کنید و قابل‌بستن (dismissible) بسازید.

هر وقت نوشته‌ای ایجاد یا به‌روزرسانی شود اجرا می‌شود. جای معمول برای ذخیرهٔ دادهٔ متاباکس.

زمان اجرا

پس از نوشته‌شدنِ یک نوشته در پایگاه داده.

امضا

add_action( 'save_post', 'my_callback', 10, 3 ); // receives $post_id, $post, $update

مثال

add_action( 'save_post', function ( $post_id ) {
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;
    if ( wp_is_post_revision( $post_id ) ) return;
    if ( ! current_user_can( 'edit_post', $post_id ) ) return;
    // ... now it is safe to save
}, 10, 1 );

نکتهٔ غافلگیرکننده

علاوه بر ذخیره‌های واقعی، روی ذخیره‌های خودکار (autosave) و بازنگری‌ها (revision) هم اجرا می‌شود. بدونِ سه محافظِ بالا، هر بار که ویرایشگر ذخیرهٔ خودکار می‌کند، متای شما با مقادیرِ خالی بازنویسی می‌شود — باگی که شبیهِ ناپدیدشدنِ تصادفیِ داده‌ها به نظر می‌رسد.

متاباکس‌ها را روی صفحهٔ ویرایشِ نوشته ثبت می‌کند.

زمان اجرا

وقتی صفحهٔ ویرایش ساخته می‌شود.

امضا

add_action( 'add_meta_boxes', 'my_callback', 10, 2 ); // receives $post_type, $post

نکتهٔ غافلگیرکننده

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

پس از ورودِ موفقِ یک کاربر اجرا می‌شود.

زمان اجرا

هنگام احراز هویتِ موفق.

امضا

add_action( 'wp_login', 'my_callback', 10, 2 ); // receives $user_login, WP_User $user

بلافاصله پس از ایجادِ یک کاربر جدید اجرا می‌شود.

زمان اجرا

هنگام ثبت‌نام.

امضا

add_action( 'user_register', 'my_callback', 10, 2 ); // receives $user_id, $userdata

نتیجهٔ احراز هویت را فیلتر می‌کند. برای مسدودکردنِ یک ورود، یک WP_Error برگردانید.

زمان اجرا

حین تلاش برای ورود.

امضا

add_filter( 'authenticate', 'my_callback', 30, 3 ); // receives $user, $username, $password

نکتهٔ غافلگیرکننده

اولویت اینجا خیلی مهم است. هستهٔ WordPress بررسی‌های خودش را در اولویت‌های 20 و 30 متصل می‌کند — اگر خیلی زود متصل شوید، پیش از آنکه حتی گذرواژه بررسی شود اجرا می‌شوید.

مسیرها و فیلدهای REST را ثبت می‌کند.

زمان اجرا

وقتی REST API مقداردهیِ اولیه می‌شود.

امضا

add_action( 'rest_api_init', 'my_callback' );

مثال

add_action( 'rest_api_init', function () {
    register_rest_route( 'myplugin/v1', '/items', array(
        'methods'             => 'GET',
        'callback'            => 'my_get_items',
        'permission_callback' => '__return_true', // BE DELIBERATE ABOUT THIS
    ) );
} );

نکتهٔ غافلگیرکننده

permission_callback الزامی است — از WP 5.5 به بعد حذفِ آن یک نوتیس (notice) ایجاد می‌کند و تنظیمِ آن روی __return_true انتهانقطه (endpoint) را کاملاً عمومی می‌کند. این برای داده‌های واقعاً عمومی خوب است و برای هر چیز دیگری یک حفرهٔ جدی است. تصمیم بگیرید، به حالتِ پیش‌فرض رها نکنید.

یک بازهٔ تکرارِ سفارشی برای wp_schedule_event() اضافه می‌کند.

زمان اجرا

وقتی WordPress فهرستِ زمان‌بندی‌های در دسترسش را می‌سازد.

امضا

add_filter( 'cron_schedules', 'my_callback' ); // receives $schedules

مثال

add_filter( 'cron_schedules', function ( $schedules ) {
    $schedules['every_five_minutes'] = array(
        'interval' => 300,             // seconds
        'display'  => __( 'Every 5 minutes', 'textdomain' ),
    );
    return $schedules;
} );

نکتهٔ غافلگیرکننده

WP-Cron یک cron واقعی نیست. فقط وقتی کسی از سایت بازدید کند اجرا می‌شود، پس یک سایتِ کم‌ترافیک، یک زمان‌بندیِ پنج‌دقیقه‌ای را هر پنج دقیقه اجرا نخواهد کرد. اگر زمان‌بندی واقعاً مهم است، WP-Cron را غیرفعال کنید (DISABLE_WP_CRON) و wp-cron.php را از یک cron سیستمیِ واقعی فراخوانی کنید.

بلافاصله پس از ذخیرهٔ یک دیدگاه اجرا می‌شود.

زمان اجرا

هنگام ثبتِ دیدگاه.

امضا

add_action( 'comment_post', 'my_callback', 10, 3 ); // receives $comment_id, $approved, $commentdata

دادهٔ دیدگاه را پیش از ذخیره فیلتر می‌کند. برای بررسیِ هرزنامه (spam) و اعتبارسنجی به کار می‌رود.

زمان اجرا

پیش از نوشته‌شدنِ دیدگاه.

امضا

add_filter( 'preprocess_comment', 'my_callback' ); // receives $commentdata

نکتهٔ غافلگیرکننده

برای رد یک دیدگاه در اینجا، wp_die() را با یک پیام فراخوانی کنید — return کردنِ false جلوی آن را نمی‌گیرد.

روی صفحهٔ دریافتِ سفارش پس از یک تسویه‌حسابِ موفق اجرا می‌شود.

زمان اجرا

وقتی مشتری به صفحهٔ تشکر می‌رسد.

امضا

add_action( 'woocommerce_thankyou', 'my_callback' ); // receives $order_id

نکتهٔ غافلگیرکننده

این جای قابل‌اتکایی برای راه‌اندازیِ فرآیندِ تحویل (fulfilment) نیست. فقط اگر مشتری واقعاً به صفحهٔ تشکر برسد اجرا می‌شود — اگر پس از پرداخت زبانه را ببندد، هرگز اجرا نمی‌شود. برای هر کاری که حتماً باید انجام شود، از woocommerce_payment_complete یا یک هوکِ انتقالِ وضعیتِ سفارش استفاده کنید.

نشانه‌گذاری را بلافاصله پیش از دکمهٔ افزودن به سبد در یک صفحهٔ محصول خروجی می‌دهد.

زمان اجرا

حین رندرِ صفحهٔ محصول.

امضا

add_action( 'woocommerce_before_add_to_cart_button', 'my_callback' );

فیلدها را در تسویه‌حسابِ کلاسیک اضافه، حذف یا مرتب‌سازیِ مجدد می‌کند.

زمان اجرا

وقتی فرمِ تسویه‌حساب ساخته می‌شود.

امضا

add_filter( 'woocommerce_checkout_fields', 'my_callback' ); // receives $fields

نکتهٔ غافلگیرکننده

این فقط بر تسویه‌حسابِ کلاسیک (کوته‌کد/shortcode) اثر می‌گذارد. تسویه‌حسابِ جدیدترِ مبتنی بر بلوک آن را کاملاً نادیده می‌گیرد و از طریقِ Slot & Fill در JavaScript سفارشی‌سازی می‌شود. این تقریباً همه را بارِ اول گیر می‌اندازد.