Содержание статьи
Замените прямое вмешательство в исходный код на внедрение пользовательских точек подключения. Это безопаснее, гибче и сохраняет совместимость при обновлениях. Главное – не нарушить существующую цепочку событий. Тщательно выбирайте имена и приоритеты. Коллизии – не редкость.
В базовой архитектуре ядра доступны два типа точек подключения: do_action() и apply_filters(). Для внедрения пользовательского действия используйте:
do_action(\'custom_action_name\', $arg1, $arg2);
А затем подключите обработчик:
add_action(\'custom_action_name\', \'my_callback_function\', 10, 2);
Не используйте имена, совпадающие с существующими триггерами ядра или популярных расширений. Проверяйте списки уже зарегистрированных точек перед добавлением своих.
Внимание! Любое действие, добавленное в раннем этапе и не проверенное на конфликт с ядром, может разрушить цепочку инициализации и вызвать критическую ошибку.
Фильтры работают аналогично. Используйте apply_filters() в нужном месте шаблона или плагина:
$value = apply_filters(\'modify_my_value\', $original_value);
И подключайте свою функцию для изменения значения:
add_filter(\'modify_my_value\', \'my_filter_function\');
Структура работы с фильтрами особенно полезна при работе с внешними API или генерацией динамического контента, когда нужно предоставить другим разработчикам возможность подменить результат без вмешательства в исходный код.
Важно помнить: приоритет влияет на порядок вызова функций, но не гарантирует уникальность. Всегда учитывайте влияние сторонних расширений.
Проверяйте наличие других обработчиков с помощью has_action() или has_filter(). Не полагайтесь на \»чистую\» среду – она иллюзорна. WP-песочница многолюдна.
Иногда уместно использовать анонимные функции, особенно в одноразовых сценариях. Но для повторного использования и модульности предпочтительнее именованные колбэки.
Значения по умолчанию должны быть обернуты в фильтры. Даже если вы уверены, что никто не будет менять их. Разработчики думают иначе, чем вы. Дайте им возможность вмешаться.
Как зарегистрировать собственный action-хук в functions.php
Сначала регистрируется триггер через функцию do_action(). Это точка, где будет выполняться привязанная логика.
Пример:
do_action( \'my_custom_action\', $arg1, $arg2 );
Это нужно вставить в шаблон, плагин или другой участок, где необходим запуск стороннего кода. Аргументы передаются обработчикам как есть.
Теперь – привязка функций. Используется add_action() в файле functions.php или любом другом подключенном скрипте.
Пример обработчика:
function my_custom_action_handler( $arg1, $arg2 ) {
// Ваша логика
}
add_action( \'my_custom_action\', \'my_custom_action_handler\', 10, 2 );
Цифра 10 – приоритет. Чем ниже значение, тем раньше исполнится. Последнее число – количество аргументов. Не совпадает – получите ошибку или NULL.
Важно! Названия событий должны быть уникальны. Проверяйте на коллизии. Никто не запретит использовать существующий идентификатор, и вы уничтожите чужую логику.
Подключение снаружи шаблонов требует осторожности. Нельзя вызывать do_action() до загрузки ядра. Не пытайтесь исполнять хуки в functions.php вне контекста событий – сломаете всё.
Внимание! При передаче объектов в параметры используйте их по ссылке, иначе изменения не сохранятся. Особенно при работе с глобальными данными.
Место регистрации do_action() – ключ. В хедере? Выполнится до всего. В цикле? Каждый раз. В footer.php? Поздно – многое уже недоступно.
Нужна динамика? Формируйте имя действия программно:
$hook = \'my_action_\' . get_post_type();
do_action( $hook, $post_id );
Гибко. Мощно. Но опасно. Проверяйте существование обработчиков через has_action(), если не уверены в контексте:
if ( has_action( \'my_action_post\' ) ) { do_action( \'my_action_post\' ); }
Закрепим. do_action() – спусковой механизм. add_action() – реакция. Контроль на всех уровнях. Протестировать – обязательно. В логах ошибок – всё.
Подключение пользовательских функций к созданному хуку
Привязывайте обработчики к кастомному действию через add_action, точно указывая имя события. Нет имени – нет вызова. Пример:
add_action(\'my_custom_event\', \'handle_my_custom_event\');
function handle_my_custom_event() {
// код, который выполнится при срабатывании
}
Если нужно передать параметры – задавайте их в do_action строго по позиции. В функции они должны приниматься в том же порядке:
do_action(\'my_custom_event\', $arg1, $arg2);
function handle_my_custom_event($first, $second) {
// $first и $second – значения из do_action
}
add_action(\'my_custom_event\', \'handle_my_custom_event\', 10, 2);
Важно! Последний аргумент
add_actionопределяет количество принимаемых параметров. Укажите недостаточно – функция не получит все данные.
Нужен приоритет? Третий аргумент в add_action. Чем меньше число – тем раньше вызов. Регистрируйте критичные задачи с приоритетом 1–5, остальные – 10 и выше.
add_action(\'my_custom_event\', \'log_my_event\', 1);
Хотите временно отключить обработчик? Используйте remove_action с теми же аргументами, что при регистрации:
remove_action(\'my_custom_event\', \'log_my_event\', 1);
Не используйте анонимные функции, если планируете снимать их позже. remove_action не сможет отследить closure.
Внимание! Хук должен быть вызван до регистрации обработчика, если результат нужен сразу. Проверяйте порядок загрузки файлов!
Соблюдайте единый стиль нейминга. Используйте префиксы. Избегайте коллизий: myplugin_prefix_event вместо просто event. Экономьте будущее время.
Сквозная проверка: has_action поможет понять, кто уже подключен. Особенно полезно при отладке или при конфликте плагинов:
if (has_action(\'my_custom_event\')) {
// отреагировать
}
Подключать – просто. Держать порядок – сложнее. Следите.
Создание фильтра (filter hook) для изменения данных на лету
Подключите фильтр с помощью add_filter(), передав в него имя точки входа, имя вашей функции и при необходимости приоритет и количество аргументов. Не изобретайте велосипед – изучите текущие фильтры ядра и тем.
add_filter( \'the_title\', \'prefix_change_title\' );
function prefix_change_title( $title ) {
if ( is_admin() ) {
return $title;
}
return \'🔥 \' . $title;
}
Этот код добавляет иконку к заголовку каждой записи на фронтенде. На первый взгляд – тривиально. Но теперь в каждом месте, где вызывается the_title(), текст будет изменён.
Внимание! Никогда не применяйте фильтр к функциям, результат которых кэшируется – это приведёт к странным побочным эффектам.
В фильтрах допустимо изменять только переданный параметр. Не нарушайте контракт – фильтры не предназначены для побочных действий. Возвращайте именно то, что от вас ожидается.
add_filter( \'comment_text\', \'strip_phone_numbers\' );
function strip_phone_numbers( $comment ) {
return preg_replace( \'/\\+?\\d[\\d\\s\\-]{8,}/\', \'[номер удалён]\', $comment );
}
- Приоритет: влияет на порядок вызова функций. Чем ниже число – тем раньше срабатывает.
- Аргументы: не всегда передаётся только один. Используйте
add_filter( \'hook\', \'callback\', 10, 2 ), если нужно больше. - Имена: избегайте дубликатов. Префиксуйте имена функций, особенно в плагинах.
Иногда стоит создавать свои точки фильтрации:
echo apply_filters( \'custom_price_output\', $price );
Так вы позволяете другим вмешаться в процесс. Контролируемо. Без хаков. Именно так работает ядро.
Тестирование и отладка пользовательских хуков в среде разработки
Всегда проверяйте регистрацию триггера с помощью has_action() или has_filter(). Это быстро отсекает ложные срабатывания и выявляет конфликт с плагинами, которые перезаписывают приоритеты.
Используйте Query Monitor. Без него отладка становится стрельбой вслепую. Он отображает все вызовы триггеров, очередность, переданные аргументы, стек вызовов. Особенно полезен при отладке событий, завязанных на жизненный цикл загрузки ядра.
Подключайте do_action(\'your_custom_hook\') в явном месте шаблона и вызывайте add_action() с максимальным уровнем логирования:
add_action(\'your_custom_hook\', function($arg) {
error_log(\'HOOK TRIGGERED: \' . print_r($arg, true));
});
Важно: всегда очищайте лог перед тестами. Старые сообщения маскируют реальную причину ошибки.
Используйте тестовую тему без сторонних зависимостей. Любой сторонний шаблон может вызывать хаос в порядке срабатывания событий. Не проверяйте поведение триггера в окружении с 30 включёнными плагинами – это бесполезно.
wp_die() – не просто средство прерывания. Добавьте его в тело обработчика и моментально поймёте, срабатывает он вообще или нет.
add_action(\'your_custom_hook\', function() {
wp_die(\'STOP. Хук активен.\');
});
Проверьте, вызывается ли вообще ваша точка в коде. Частая ошибка – забыли вставить do_action() в нужное место или вызывается условно (например, в админке, а вы ждёте его на фронте).
Хотите уверенности? Напишите unit-тесты через wp-tests и PHPUnit. Моделируйте вызов события, проверяйте результат. Это не \»просто для энтузиастов\», это единственный способ быть уверенным, что в релизе всё будет работать предсказуемо.
Снимайте логи времени исполнения каждого обработчика. Вешайте несколько функций с разным приоритетом, анализируйте порядок. Иначе вы не поймёте, почему сбивается логика.
add_action(\'your_custom_hook\', function() {
error_log(\'Priority 10\');
}, 10);
add_action(\'your_custom_hook\', function() {
error_log(\'Priority 5\');
}, 5);
Подключайте Xdebug. Пошаговая отладка – единственный путь найти баг в цепочке, где участвуют ядро, шаблон, сторонний плагин и ваша логика.
Нет Xdebug? Тогда логируйте всё подряд. Путь к файлу, строку, параметры – каждый вызов. Только так вы отыщете перекрытие обработчиков или некорректную точку входа.