Архитектура хуков 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 уже выполнился. Обычно это означает подключение вашего удаления к более позднему действию.