Action Hook

Механизм состоит из двух половин. В ядре, теме или плагине стоит вызов do_action( 'имя', ...аргументы ) — это точка, где «что-то произошло». Сторонний код подписывается на неё через add_action(), и когда выполнение доходит до точки, WordPress по очереди вызывает всех подписчиков. Так плагины меняют поведение сайта, не трогая файлы ядра: обновление WordPress не сотрёт доработку.

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

Приоритет и число аргументов

У add_action( $hook, $callback, $priority, $accepted_args ) два необязательных параметра, о которых часто забывают. Приоритет по умолчанию равен 10: функции с меньшим числом выполняются раньше. Параметр $accepted_args по умолчанию равен 1 — если хук передаёт три значения, а вы не указали 3, функция получит только первое.

Чтобы отключить чужой обработчик, вызывают remove_action() с тем же именем функции и тем же приоритетом, что при подключении. Анонимную функцию так снять почти невозможно, поэтому в плагинах обработчики лучше делать именованными или методами класса.

Пример: своя точка расширения

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

// В плагине оплаты, после подтверждения платежа
do_action( 'myshop_order_paid', $order_id, $amount );

// В другом месте: уведомление менеджеру
add_action( 'myshop_order_paid', 'myshop_notify_manager', 20, 2 );
function myshop_notify_manager( $order_id, $amount ) {
    wp_mail( 'sales@example.ru', 'Оплата заказа ' . $order_id, 'Сумма: ' . $amount );
}

Как отладить

Функция has_action() показывает, подключён ли обработчик, did_action() — сколько раз точка уже сработала за запрос. Для наглядного списка всех хуков страницы удобен плагин Query Monitor.