4.1 Действия (Actions или экшены)

Действия – один из двух видов Хуков (Hooks). Они обеспечивают способ выполнения функции в определенных точках выполнения в ядре WordPress Core, плагинах и темах. Они являются аналогом Фильтров (Filters). Дополнительная информация о разнице между действиями и фильтрами приведена по этой ссылке.

Добавление действия

Процесс добавления действия включает в себя два этапа:

Создание функции обратного вызова (callback)

Сначала создайте функцию обратного вызова (callback function). Эта функция будет запущена, когда будет выполнено действие, к которому она привязана (или зацеплена хуком).

Функция обратного вызова похожа на обычную функцию: она должна быть префиксной и должна быть в файле functions.php или где-нибудь в вызываемом месте. Параметры, которые она должна принять, будут определяться действием (action), к которому вы подключаетесь (цепляетесь хуком); большинство хуков хорошо определены, поэтому просмотрите документацию хуков, чтобы увидеть, какие параметры выбранное вами действие будет передавать в вашу функцию.

Присваивание (хук) вашей функции обратного вызова

Во-вторых, добавьте callback-функцию к действию (action). Это называется “перехватом” или хукингом и сообщает экшену, что нужно запустить вашу функцию обратного вызова, когда действие (action) запущено.

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

  1. строка (string) $tag – название действия, к которому вы цепляетесь (hook)
  2. вызываемая $function_to_add имя вашей функции обратного вызова

В примере ниже будет запущена функция wporg_callback() при выполнении инициализации хука:

function wporg_callback() {
    // сделать что-то
}
add_action( 'init', 'wporg_callback' );

Список доступных хуков можно найти в главе “Хуки“.

Как только у вас появится больше опыта, просмотр исходного кода ядра WordPress позволит вам находить наиболее подходящие хуки.

Дополнительные параметры

add_action() может принимать два дополнительных параметра, int $priority для приоритета, отдаваемого функции обратного вызова, и int $accepted_args для количества аргументов, которые будут переданы функции обратного вызова.

Приоритет

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

WordPress определяет порядок выполнения функций обратного вызова на основе двух вещей и первый способ – это ручная установка приоритета. Это делается с помощью третьего аргумента add_action().

Вот некоторые важные факты о приоритетах:

  • приоритеты – положительные целые числа, обычно от 1 до 20
  • приоритет по умолчанию (т.е. приоритет, назначенный, когда значение приоритета не задается вручную) равен 10
  • теоретически нет верхнего предела для значения приоритета, но реалистичный верхний предел составляет 100

Функция с приоритетом 11 будет выполняться после функции с приоритетом 10; а функция с приоритетом 9 будет выполняться перед функцией с приоритетом 10.

Второй способ определения порядка следования функций обратного вызова – это просто порядок, в котором она была зарегистрирована в пределах одного и того же значения приоритета. Таким образом, если две функции обратного вызова зарегистрированы для одного и того же хука с одинаковым приоритетом, они будут запущены в том порядке, в котором они были зарегистрированы.

Например, все следующие функции обратного вызова зарегистрированы для хука init, но с разными приоритетами:

add_action('init', 'wporg_callback_run_me_late', 11);
add_action('init', 'wporg_callback_run_me_normal');
add_action('init', 'wporg_callback_run_me_early', 9);
add_action('init', 'wporg_callback_run_me_later', 11);

В примере выше:

  • Первой выполняемой функцией будет функция wporg_call_backrun_me_early(), так как она имеет ручной приоритет 9
  • Далее, wporg_callback_run_me_normal(), потому что она не имеет установленного приоритета, а значит, ее приоритет 10
  • Далее выполняется функция wporg_callback_run_me_late(), поскольку ее ручной приоритет 11
  • Наконец, запущена функция wporg_callback_run_me_later(): она также имеет приоритет 11, но была подключена после wporg_callback_run_me_late().

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

Иногда, желательно для функции обратного вызова (callback-функции) иметь возможность принимать какие-то дополнительные данные, связанные с действием (action), которое подключается (цепляется хуком).

Например, когда WordPress сохраняет запись и запускает хук save_post, он передаёт в функцию обратного вызова два параметра: идентификатор сохраняемой записи и сам объект записи:

do_action( 'save_post', $post->ID, $post );

Когда функция обратного вызова зарегистрирована для хука save_post, то она может указать, что хочет получить эти два параметра. Она делает это, сказав add_action ожидать их, поместив 2 в качестве четвертого аргумента:

add_action('save_post', 'wporg_custom', 10, 2);

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

function wporg_custom( $post_id, $post ) {
    // сделать что-то
}
Хорошая практика – давать параметрам функции обратного вызова то же имя, что и переданным параметрам, или как можно более близкое.

Наверх ↑