Покажчик хуків WordPress

Пошуковий покажчик дій та фільтрів WordPress, якими розробники справді користуються — з точною сигнатурою add_action/add_filter, моментом спрацювання, робочим прикладом і тим, на чому люди спотикаються.

39 хуків — із точною сигнатурою add_action / add_filter, моментом спрацювання, робочим прикладом і тим, на чому люди зазвичай спотикаються. 1 позначено як неперевірені — ми не звіряли кількість їхніх аргументів із вихідним кодом WordPress і радше зазначимо це, ніж видаватимемо здогад за факт.

Цей перелік не вичерпний і не претендує на це — у WordPress тисячі хуків. Він охоплює ті, до яких люди звертаються насправді.

39 з 39

Виконується після того, як WordPress завершив завантаження, але до того, як надіслано будь-які заголовки. Стандартне місце для реєстрації власних типів записів, таксономій і правил перезапису URL.

Спрацьовує

На кожному запиті — і на фронтенді, і в адмінці — після завантаження ядра, плагінів і теми.

Сигнатура

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().

Єдине правильне місце для підключення 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' );

Підводний камінь

НЕ підключайте тут скрипти чи стилі — використовуйте wp_enqueue_scripts, який дозволяє WordPress керувати залежностями та усувати дублювання. Вивід тегу <script> напряму у wp_head обходить усе це, і саме тому стільки сайтів завантажують jQuery тричі.

Виводить вміст безпосередньо перед </body>. Правильне місце для фрагментів аналітики та відкладеної розмітки.

Спрацьовує

У кінці сторінки фронтенду.

Сигнатура

add_action( 'wp_footer', 'my_callback' );

Підводний камінь

Тема, яка забуває викликати wp_footer(), ламає панель адміністратора, ламає будь-який плагін, що підключає скрипт у футер, і автоматично відхиляється під час перевірки тем на 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

Підводний камінь

Він не діє на записи з РУЧНИМ уривком — такі використовуються дослівно. До того ж багато тем самі встановлюють цей фільтр, тож часто потрібен високий номер пріоритету, щоб перемогти.

Змінює рядок, що додається в кінець скороченого уривка. Стандартно — " […]".

Спрацьовує

Коли автоматично згенерований уривок скорочується.

Сигнатура

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, нічого не повертайте.

Фільтрує сирий SQL-вираз WHERE у запиті.

Спрацьовує

Під час складання 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 збирається згенерувати для завантаження. Видаліть розмір із масиву, щоб припинити його генерацію.

Спрацьовує

Під час завантаження, до створення похідних файлів.

Сигнатура

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 відкотиться до повнорозмірного оригіналу — а це гірше за той дисковий простір, який ви зекономили. І це зупиняє створення лише НОВИХ файлів; наявні залишаються, доки ви їх не перегенеруєте.

Задає якість 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. Повернення false чи викидання винятку не дадуть бажаного результату.

Фільтрує масив метаданих (включно зі згенерованими розмірами) після обробки вкладення.

Спрацьовує

Після створення похідних зображень під час завантаження.

Сигнатура

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 — це саме МОЖЛИВІСТЬ (capability), а не роль. Передача «administrator» ніби працює (бо в деяких конфігураціях адміністратори мають можливість із такою назвою), а потім тихо надає доступ не тим людям. Використовуйте manage_options.

Виводить сповіщення вгорі екрана адмінки.

Спрацьовує

Під час рендерингу сторінки адмінки.

Сигнатура

add_action( 'admin_notices', 'my_callback' );

Підводний камінь

Він спрацьовує на КОЖНОМУ екрані адмінки. Плагін, який безумовно показує сповіщення «дякуємо за встановлення!» на всіх них, — це найненависніший патерн в адмінці WordPress. Захистіть його умовою і зробіть таким, що закривається.

Виконується щоразу, коли запис створюється або оновлюється. Звичне місце для збереження даних метабоксів.

Спрацьовує

Після того, як запис збережено в базі даних.

Сигнатура

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 );

Підводний камінь

Він спрацьовує на АВТОЗБЕРЕЖЕННЯХ і РЕДАКЦІЯХ, а не лише на справжніх збереженнях. Без трьох перевірок, наведених вище, ваші метадані перезаписуються порожніми значеннями щоразу, коли редактор автозберігає, — вада, яка виглядає так, ніби дані випадково зникають.

Реєструє метабокси на екрані редагування запису.

Спрацьовує

Коли будується екран редагування.

Сигнатура

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 його відсутність викликає попередження, а встановлення його в __return_true робить кінцеву точку повністю публічною. Це нормально для справді публічних даних і серйозна діра для всього іншого. Приймайте рішення свідомо, не покладайтеся на замовчування.

Додає власний інтервал повторення для 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

Фільтрує дані коментаря перед збереженням. Використовується для перевірки на спам і валідації.

Спрацьовує

До запису коментаря.

Сигнатура

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

Підводний камінь

Щоб відхилити коментар тут, викличте wp_die() з повідомленням — повернення false його не зупинить.

Виконується на сторінці отримання замовлення після успішного оформлення.

Спрацьовує

Коли клієнт потрапляє на сторінку подяки.

Сигнатура

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

Підводний камінь

Це НЕнадійне місце для запуску виконання замовлення. Він спрацьовує лише тоді, коли клієнт справді досягає сторінки подяки — якщо після оплати він закриє вкладку, хук ніколи не виконається. Для всього, що обов'язково має статися, використовуйте woocommerce_payment_complete або хук переходу статусу замовлення.

Виводить розмітку безпосередньо перед кнопкою додавання в кошик на сторінці товару.

Спрацьовує

Під час рендерингу сторінки товару.

Сигнатура

add_action( 'woocommerce_before_add_to_cart_button', 'my_callback' );

Додає, видаляє або змінює порядок полів на класичному оформленні замовлення.

Спрацьовує

Коли будується форма оформлення замовлення.

Сигнатура

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

Підводний камінь

Це впливає лише на КЛАСИЧНЕ (на шорткоді) оформлення замовлення. Новіше оформлення на блоках повністю його ігнорує й налаштовується через Slot & Fill у JavaScript. На цьому першого разу спотикаються майже всі.