Фильтры и события (хуки) в WordPress

В WordPress фильтры (filter) и события (action) называются "хуками" (по английски "hook" - "крючок"). Фильтры позволяют обрабатывать передаваемое значение, возвращая результат преобразования. События аналогичны фильтрам, но они ничего не возвращают.

К хукам обычно прикрепляются пользовательские функции, которые срабатывают в момент вызова хука. Такое поведение в программировании называется "перехват".

Во время вызова функции, которая прикреплена к хуку, ей можно передать некоторые параметры (данные). Приведём простейший пример хука:

<?php 
function MouseDC(){ // произвольная функция для будущего события (не возвращает ничего)
   echo 'Я люблю сыр!';
}

add_action('myHook', 'MouseDC'); // привяжем функцию к хуку

do_action('myHook'); // выполним хук. Получим надпись "Я люблю сыр!"

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

<?php 
function Mouse($var){ // произвольная функция для будущего события (не возвращает ничего)
   echo 'Я люблю ' . $var . '.';
}
function Cat($var){ // произвольная функция для будущего события (не возвращает ничего)
   echo 'А кошки не любят ' . $var . '!';
}

add_action('myHook', 'Mouse'); // привяжем первую функцию к хуку
add_action('myHook', 'Cat'); // привяжем вторую функцию к хуку

$food = 'сыр';
do_action('myHook', $food); // выполним хук. Получим надпись "Я люблю сыр. А кошки не любят сыр!"

Обратите внимание, что один и тот же параметр был передан во все функции одновременно.

Далее в этой статье рассмотрим раздельно фильтры и события. Первые вызываются с помощью функции add_filter(), вторые с помощью и add_action(). По сути это две абсолютно одинаковые функции, они делают одно и тоже и принимают одинаковый набор параметров. Вы можете даже поменять местами эти функции в коде, это не вызовет ошибки.

Фильтры в WordPress

Для создания фильтров используется функция:

add_filter( $hook_name, $function, $priority, $args_num )

$hook_name	строка	Название фильтра, для которого будет срабатывать функция.
$function	строка	Название функции (в виде строки), которая будет срабатывать. Если функция находится внутри класса, то нужно указать массив: array('название_класса', 'название_функции').
$priority	число	Приоритет выполнения функций для фильтра. Функция с приоритетом 20 будет выполняться после функции с приоритетом 10. По умолчанию приоритет равен 10.
$args_num	число	Количество принимаемых аргументов. Если фильтр может принимать два аргумента, то надо поставить цифру 2 и т.д (по умолчанию - 1).

После того как фильтр создан, его необходимо вызвать. Для этого используется:

apply_filters( $hook_name, $value, $args )

$hook_name	строка	Название фильтра, для которого будет срабатывать функция.
$value	любой тип	Значение, которое будет передано функции.
$args	любой тип	Дополнительные значение, которое будет передано функции.

Хуки должны иметь уникальные значения. И эти значения не должны совпадать с уже существующими хуками WordPress. И их более 2 000 (список хуков WordPress)

События в WordPress

Как сказали ранее, функции для работы с событиями аналогичны функциям работы с фильтрами. Аргументы совпадают.

Для добавления функции к событию используется "add_action":

add_action( $hook_name, $function, $priority, $args_num )

А чтобы запустить добавленные к событию функции необходимо выполнить:

do_action( $hook_name, $args )

Удаление хука в WordPress

Для удаления функции, которая привязана к фильтру или событию, используется несколько функций. Для событий - remove_action. Для функций - remove_filter. Обе функции принимают три аргумента. Первый - названия фильтра или события, второй - название привязанной функции, третий - приоритет удаления:

remove_action( $hook_name, $function, $priority )

remove_filter( $hook_name, $function, $priority )

Третий параметр очень важный. Если при добавлении функции был указан приоритет, то при удалении его тоже нужно указывать. Причём нужно использовать то же самое значение. Иначе удаления хука не произойдёт.

Попробуем модифицировать примеры из начала этой статьи, чтобы продемонстрировать удаление:

<?php 
function MouseDC(){ // произвольная функция для будущего события (не возвращает ничего)
   echo 'Я люблю сыр!';
}

add_action('myHook', 'MouseDC'); // привяжем функцию к хуку

remove_action('myHook', 'MouseDC'); // удалим функцию с хука

do_action('myHook'); // выполним хук. Ничего не будет выведено

Теперь модифицируем второй пример, с двумя функциями на хуке. Но удалим только первую:

<?php 
function Mouse($var){ // произвольная функция для будущего события (не возвращает ничего)
   echo 'Я люблю ' . $var . '.';
}
function Cat($var){ // произвольная функция для будущего события (не возвращает ничего)
   echo 'А кошки не любят ' . $var . '!';
}

add_action('myHook', 'Mouse'); // привяжем первую функцию к хуку
add_action('myHook', 'Cat'); // привяжем вторую функцию к хуку

remove_action('myHook', 'Mouse'); // удалим функцию с хука

$food = 'сыр';
do_action('myHook', $food); // выполним хук. Получим надпись "А кошки не любят сыр!"

Другие функции хуков в WordPress

Рекомендуем ознакомиться с другими функциями (названия функций ведут на страницы сайта WordPress).

Функция	Описание
did_action	Возвращает число вызовов указанного события (хука).
has_action()	Проверяет была ли зарегистрировано событие для хука.
doing_action()	Возращает название событие, которое сейчас обрабатывается.
has_filter()	Проверяет была ли зарегистрирована функция для хука.
current_filter()	Возвращает название текущего фильтра.
doing_filter()	Возращает название фильтра, которое сейчас обрабатывается.
remove_all_filters()	Удаляет все хуки у указанного фильтра.