add_action()
Прикрепляет указанную PHP функцию на указанный хук. Указанная функция сработает в момент события, которое в свою очередь запускается с помощью do_action().
Хук на который цепляется функция создается (инициализируется) с помощью функции do_action().
События (actions), в отличии от Фильтров - add_filter(), нужны, чтобы выполнить какое-либо действие в нужный момент, тогда как фильтры передают и получают обратно данные, которые затем используются.
Смотрите также: список всех важных событий в порядке их выполнения.
Неофициально: фильтры - это те же самые события, работают они точно также и их можно использовать как события (вместо add_filter() можно использовать функцию add_action() и наоборот). Например, можно не изменяя возвращать полученные данные, но помимо этого выполнять какую-нибудь операцию (например запись в БД). Правда это бывает нужно очень редко. Все места где нужно вмешаться в код движка, разработчики, пытаются предусмотреть и вставить в это место событие.
О фильтрах и событиях читайте в этой заметке: как работают хуки в WordPress
Хуков нет.
Возвращает
true.
Использование
add_action( $tag, $callback, $priority, $accepted_args );
- $tag(строка) (обязательный)
- Название хука-события. На него будет зацеплена функция указанная в $callback.
- $callback(строка/callable) (обязательный)
- Название функции, которая должна быть вызвана во время срабатывания действия, т.е. функция которую цепляем к хуку. callable.
- $priority(число)
- Приоритет выполнения функции. Если на этот же хук "прицеплены" еще функции, то приоритет будет решать последовательность их выполнения. Меньше число - раньше выполняется, т.е. 10 будет выполняться раньше чем 20.
По умолчанию: 10 - $accepted_args(число)
- Число аргументов, которые принимает функция. Событие должно передавать указанное число параметров.
По умолчанию: 1
Примеры
#1 Получение аргумента
do_action() передает аргумент в функцию и его можно использовать. В предыдущем примере это был ID поста, но мы его не использовали, потому он нам не был нужен. Теперь, пример того, как использовать передаваемый аргумент:
add_action( 'comment_id_not_found', 'echo_comment_id', 10, 1 );
function echo_comment_id( $comment_ID ){
echo "I just received ". $comment_ID;
}
#2 Обычный хук
Будем отправлять письмо друзьям, при публикации нового поста:
add_action( 'publish_post', 'email_friends' );
function email_friends( $post_ID ){
$friends = 'bob@example.org, susie@example.org';
wp_mail( $friends, "sally's blog updated", 'I just put something on my blog: http://blog.example.com' );
}
Точно так же можно зарегистрировать этот хук через add_filter():
add_filter( 'publish_post', 'email_friends' );
#3 Анонимная функция
В качестве колбэк функции можно передавать анонимную функцию, например:
add_action( 'wp_head', static function(){
echo 'something';
} );
Такие анонимные функции не работают совместно с PHP ускорителями.
Читайте также: Зачем нужен static при объявлении анонимных функций?
Также, важно знать, что такую анонимную функцию в дальнейшем почти невозможно удалить функцией remove_action().
#4 Добавление события из PHP класса
Если для события нужно использовать как-либо метод PHP класса, то во втором аргументе, вместо названия функции, нужно указать массив, где первым аргументом будет название класса (для static метода) или экземпляр класса (для public метода), а вторым название метода этого класса.
Экземпляр класса находится в переменной $this:
// Подключение метода класса за пределами класса
add_action( 'wp_head', array( 'My_Class', 'my_static_method' ) );
class My_Class {
public function __construct() {
// Подключение метода класса внутри класса
add_action( 'save_post', array( $this, 'my_public_method' ) );
add_action( 'save_post', array( __CLASS__, 'my_static_method' ) );
}
public function my_public_method( $post_id ) {
// код функции
}
static function my_static_method( $post_id ) {
// код функции
}
}
Заметки
Чтобы узнать сколько аргументов передает событие, найдите его в коде и посмотрите. Например, тут передается 2 аргумента:
do_action( 'save_post', $post_ID, $post );
и для такого хука, код зацепки будет выглядеть так:
add_action( 'save_post', 'my_save_post', 10, 2 );
и функция обработчик (callback) получит 2 аргумента:
function my_save_post( $post_ID, $post ){
// здесь код функции
}Список изменений
| С версии 1.2.0 | Введена. |
Код add_action() add action WP 6.4.1
function add_action( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
return add_filter( $hook_name, $callback, $priority, $accepted_args );
}