Архітектура хуків WordPress: дії проти фільтрів, пояснення

Кожен плагін WordPress робить одне з двох: він виконує код у певний момент (дія) або змінює значення перед його використанням (фільтр). Ось і все. Вся екосистема плагінів WordPress побудована на цьому розрізненні.

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

Дії: зробити щось у певний момент часу

Хук дії — це сигнал, який WordPress (або інший плагін) надсилає в певний момент. Ви прикріплюєте функцію до цього сигналу, і ваша функція виконується, коли сигнал спрацьовує.

add_action( 'wp_enqueue_scripts', 'my_plugin_load_assets' );

function my_plugin_load_assets() {
    wp_enqueue_style( 'my-plugin', plugin_dir_url( __FILE__ ) . 'style.css' );
    wp_enqueue_script( 'my-plugin', plugin_dir_url( __FILE__ ) . 'script.js', ['jquery'], '1.0', true );
}

wp_enqueue_scripts спрацьовує, коли WordPress готується завантажити ресурси для фронтенду. Підключення до нього — це правильний спосіб завантажити CSS та JS, а не вставляти теги <script> безпосередньо в шаблони.

Поширені хуки дій, які ви будете використовувати постійно:

• init — спрацьовує рано, добре підходить для реєстрації типів записів і таксономій
• wp_enqueue_scripts — завантаження ресурсів фронтенду
• admin_enqueue_scripts — завантаження ресурсів адмін-панелі
• save_post — спрацьовує під час збереження запису, добре підходить для обробки користувацьких полів
• wp_ajax_{action} — обробка AJAX-запитів від автентифікованих користувачів
• wp_ajax_nopriv_{action} — обробка AJAX-запитів від неавторизованих користувачів

Фільтри: змінити значення перед його використанням

Хук фільтра надає вам значення, дозволяє його змінити та очікує, що ви повернете змінену версію. Потім WordPress використовує ваше змінене значення замість оригінального.

add_filter( 'the_content', 'my_plugin_append_cta' );

function my_plugin_append_cta( $content ) {
    if ( ! is_single() ) {
        return $content;
    }
    $cta = '<div class="post-cta">Готові спробувати PAGEnza? <a href="#">Почніть безкоштовно →</a></div>';
    return $content . $cta;
}

Критичне правило: завжди повертайте щось із фільтра. Якщо ви забудете return, значення стане null, і ви зламаєте все, що його використовувало.

Поширені хуки фільтрів:

• the_content — вміст запису перед відображенням
• the_title — заголовок запису
• wp_nav_menu_items — HTML меню навігації
• upload_mimes — дозволені типи завантаження файлів
• plugin_action_links_{plugin-file} — посилання, що відображаються на сторінці списку плагінів

Як PAGEnza AI використовує хуки

Коли Plugin Builder генерує плагін, він структурує код навколо класу з методами, прикріпленими до хуків у конструкторі. Цей шаблон уникає конфліктів імен глобальних функцій і зберігає код організованим.

class My_Plugin {
    public function __construct() {
        add_action( 'init', [ $this, 'register_post_type' ] );
        add_action( 'wp_enqueue_scripts', [ $this, 'load_assets' ] );
        add_filter( 'the_content', [ $this, 'append_content' ] );
    }

    public function register_post_type() { /* ... */ }
    public function load_assets() { /* ... */ }
    public function append_content( $content ) {
        // завжди повертати
        return $content;
    }
}

new My_Plugin();

Сканування безпеки спеціально перевіряє, чи містять AJAX-обробники перевірку nonce та перевірку прав доступу перед виконанням будь-яких дій:

add_action( 'wp_ajax_my_action', [ $this, 'handle_ajax' ] );

public function handle_ajax() {
    // Безпека: перевірка nonce
    check_ajax_referer( 'my_nonce_action', 'nonce' );

    // Безпека: перевірка дозволів
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_send_json_error( 'Недостатньо прав', 403 );
    }

    // Тепер безпечно обробляти
    $data = sanitize_text_field( $_POST['data'] ?? '' );
    wp_send_json_success( [ 'result' => $data ] );
}

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

Пріоритет та черга хуків

Коли до одного хука прикріплено кілька функцій, вони виконуються в порядку пріоритету (менше число = виконується першим). Пріоритет за замовчуванням — 10.

add_action( 'init', 'runs_first', 5 );
add_action( 'init', 'runs_second', 10 );   // за замовчуванням
add_action( 'init', 'runs_last', 20 );

Це важливо, коли ваш плагін повинен виконатися до або після коду іншого плагіна. Якщо ви змінюєте щось, що також змінює інший плагін, пріоритет визначає, хто виграє.

Поширений шаблон: якщо ви перевизначаєте фільтр теми, використовуйте пріоритет 20 або вище, щоб переконатися, що ви виконуєтеся після коду теми.

Видалення хуків

Ви можете видалити хук, який додав хтось інший — включно з хуками теми та плагінів:

remove_action( 'wp_head', 'wp_generator' );  // видаляє версію WP з <head>
remove_filter( 'the_content', 'wpautop' );   // видаляє автоматичне обгортання параграфів

Умова: ви можете видалити хук, лише якщо ви викличете remove_action/remove_filter після того, як оригінальний add_action/add_filter виконався. Це зазвичай означає підключення вашого видалення до пізнішої дії.