Хуки и фильтры в WordPress: как не сломать сайт

В WordPress действие обычно запускает побочный эффект, а фильтр возвращает изменённое значение. Если перепутать их, указать неверное число аргументов или повесить обработчик не на тот этап загрузки, результатом станет не только неправильный заголовок: можно получить повторные письма, сломанный вывод или фатальную ошибку. Ниже — практические правила и примеры для WordPress 6.x; перед внедрением сверяйте сигнатуры конкретного хука с документацией и исходным кодом используемой версии.

Сначала определите, что именно должен делать код

Хуки позволяют расширять WordPress и плагины без правки их файлов. Это важно при обновлениях: изменения в файлах ядра или плагина могут быть затёрты. Но слово «хук» объединяет два разных механизма.

• Действие сообщает: «сейчас происходит событие». Обработчик выполняет задачу, например регистрирует меню или отправляет данные во внешний сервис. Возвращаемое им значение WordPress не использует.
• Фильтр передаёт значение обработчику и ждёт это значение обратно. Фильтр может изменить заголовок, содержимое или параметры запроса.

Для действия используют add_action(), для фильтра — add_filter(). Внутри WordPress оба механизма работают через систему хуков, но выбор функции помогает читателю кода понять намерение. Фильтр, который ничего не возвращает, способен превратить строку в пустое значение; действие, от которого ждут изменения данных, такого изменения не сделает.

Фильтр должен вернуть значение, которое получил, даже если не меняет его. Действие должно выполнять работу, а не притворяться способом изменить данные.

Добавляйте обработчик в правильной точке

В простом плагине или файле темы зарегистрируйте обработчики после загрузки WordPress, но не запускайте бизнес-логику прямо при подключении файла. Например, регистрацию меню обычно связывают с действием init, а не выполняют безусловно в глобальной области видимости.

Пример совместим с WordPress 6.x. Вызовы функций показаны полностью, без сокращённых фрагментов:

<?php
add_action( 'init', 'acme_register_content_type' );

function acme_register_content_type() {
    register_post_type(
        'acme_event',
        array(
            'public' => true,
            'label'  => 'События',
        )
    );
}

add_filter( 'the_title', 'acme_mark_event_title', 10, 2 );

function acme_mark_event_title( $title, $post_id ) {
    if ( 'acme_event' !== get_post_type( $post_id ) ) {
        return $title;
    }

    return '[Событие] ' . $title;
}

Второй обработчик получает два аргумента: значение заголовка и идентификатор записи. Число 2 в четвёртом параметре add_filter() говорит WordPress передать оба. Без него callback по умолчанию рассчитан на один аргумент. В реальном проекте проверьте, в каком контексте вызывается фильтр the_title: он может срабатывать при выводе заголовка в разных частях сайта, и метка может оказаться неуместной, например в навигации.

Для собственного функционала предпочтительнее отдельный плагин, а не правка файлов WordPress или стороннего плагина. Если код живёт в теме, при смене темы он перестанет работать. Для небольшого сайта можно использовать дочернюю тему, но это не решает вопрос переноса функциональности вместе с темой.

Приоритет и аргументы: две настройки, которые часто путают

У add_action() и add_filter() есть параметры приоритета и числа принимаемых аргументов. Приоритет — третий параметр: по умолчанию он равен 10. Обработчики запускаются по возрастанию приоритета; при одинаковом значении важен порядок регистрации. Четвёртый параметр задаёт число аргументов, которые WordPress передаст функции.

Количество аргументов в объявлении функции и в регистрации должно совпадать с реальной сигнатурой хука. Смотрите страницу справочника для конкретного хука: документация обычно показывает аргументы, но при работе с плагином также проверьте, как и когда он вызывает этот хук. Название само по себе не гарантирует, что callback получит нужные данные.

Снимайте обработчик только той же функцией

Иногда нужно убрать действие или фильтр, добавленный другим кодом. Для этого существуют remove_action() и remove_filter(). Им нужно передать тот же хук, callback и приоритет, с которыми обработчик зарегистрировали. Если не совпадёт хотя бы один параметр, снятие не сработает.

С анонимными функциями и методами объектов возникает дополнительная сложность: для удаления нужно располагать тем же callable, который был передан при добавлении. Без ссылки на него повторно созданная анонимная функция — уже другой обработчик. Если предполагаете, что код понадобится отключать, объявляйте именованную функцию или храните callable и документируйте выбранный приоритет.

Не пытайтесь «перебить» чужую логику случайным приоритетом. Сначала найдите регистрацию исходного обработчика и выясните, когда он запускается. Иначе обновление плагина может поменять порядок вызовов, а ваш код останется с прежними предположениями.

Частые ошибки и как их искать

• Фильтр ничего не возвращает. Страница теряет текст или получает некорректное значение. Добавьте возврат исходного значения во всех ветках, где менять его не нужно.
• Callback ждёт аргумент, которого нет. Проверьте сигнатуру хука и четвёртый параметр регистрации. Включите журналирование ошибок на тестовой среде, а не показывайте ошибки посетителям.
• Обработчик срабатывает слишком рано. Перенесите регистрацию или выполнение на подходящее действие загрузки; конкретная точка зависит от API, которое используете.
• Функция выполняется дважды. Найдите повторную регистрацию: она могла попасть и в плагин, и в тему, либо выполняться при повторном подключении файла.
• Удаление не работает. Сверьте точное имя callback, хук и приоритет. Для метода объекта проверьте, что используется нужный экземпляр объекта.

Ошибки воспроизводите на тестовом сайте с той же версией WordPress, темой и набором плагинов, что и на рабочем. Если проблема появляется только с активным плагином, поищите регистрацию хука в его исходниках и зафиксируйте, какая версия его добавила: при обновлении реализация может измениться.

Когда это решение ломается

Хуки не дают гарантии, что нужный код всегда выполнится в ожидаемом контексте. Один и тот же фильтр может вызываться при формировании страницы администратора, REST-ответа, письма или фоновой задачи. Изменение без проверки контекста способно затронуть все эти сценарии. Учитывайте также повторные вызовы: обработчик не должен без необходимости отправлять письмо, создавать запись или повторно менять уже изменённое значение.

Осторожно относитесь к фильтрам, которые преобразуют HTML или SQL. Ошибка может затронуть не одну страницу, а все места, где срабатывает хук. Не используйте фильтр для обхода проверок доступа и не считайте сам факт вызова callback подтверждением, что пользователь имеет право на действие. Проверки прав и очистка данных требуют отдельного решения.

При диагностике записывайте входные значения и контекст без персональных данных и секретов. Сначала проверяйте тестовую среду, затем выкладывайте небольшое изменение и наблюдайте за журналом ошибок и затронутой функцией. Универсальных цифр допустимой нагрузки для любого хука нет: измеряйте длительность именно той операции, которую добавили, на своём сайте.

Хук¹ — именованная точка расширения в WordPress: ядро или плагин вызывает её, чтобы подключённый код мог отреагировать на событие или изменить передаваемые данные.

Что делать дальше

Возьмите один обработчик из своего проекта и проверьте четыре вещи: правильный ли выбран тип хука, совпадает ли число аргументов, возвращает ли фильтр значение во всех ветках и не регистрируется ли callback повторно. Затем найдите документацию именно для используемого хука и проверьте сценарии страницы, админки и фонового запуска, если они относятся к вашему сайту.