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

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

Действие (action) — это функция PHP, вызываемая через определенный хук действия при посещении пользователем страницы WordPress. Веб-разработчики могут добавлять собственные функции в список действий или удалять уже существующие, добавляя скрипт хука действия wp_head() перед закрывающим тегом (</head>) любой страницы.

Хуки действий являются контекстными, что означает, что не все страницы WordPress вызывают их. На странице WordPress Plugin Action Reference представлен полный список хуков действий и контекстов, в которых они вызываются.

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

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

Создание функции обратного вызова (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 ) {
// сделать что-то
}

Хорошая практика — давать параметрам функции обратного вызова то же имя, что и переданным параметрам, или как можно более близкое.

Добавление функций к хуку действия в файле плагина требует вызова функции add_action() как минимум с двумя параметрами.

// Хук для действия 'init', которое вызывается после того, как WordPress закончит загрузку основного кода

add_action( 'init', 'add_Cookie' );

// Установка cookie с текущим временем суток

function add_Cookie() {
 setcookie("last_visit_time", date("r"), time()+60*60*24*30, "/");
}

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

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

Справка. Callback (англ. call — вызов, англ. back — обратный) или функция обратного вызова в программировании — передача исполняемого кода в качестве одного из параметров другого кода.

Четвертый параметр, который также является необязательным, содержит количество аргументов или параметров, которые может принимать пользовательская функция. Значение по умолчанию равно 1.

Пример кода плагина для отображения текста после футера каждой страницы

Этот пример плагина вызывает хук действия wp_footer() перед закрывающим тегом </body> каждой страницы и добавляет новую функцию mfp_Add_Text(). Поскольку эта функция является частью плагина, она будет работать даже после смены темы.

Сохраните этот пример как PHP-файл и загрузите его в папку plugins, которая находится внутри папки wp-content.

<?php
/*
Plugin Name: Add Text To Footer
*/
// Цепляем хук действия 'wp_footer', добавляем в него функцию с именем 'mfp_Add_Text'

add_action("wp_footer", "mfp_Add_Text");
 
// Определяем функцию 'mfp_Add_Text'

function mfp_Add_Text()
{
  echo "<p style='color: black;'>After the footer is loaded, my text is added!</p>";
}

На скриншоте ниже видим, что после активации плагина через панель администратора WordPress выводит на сайте следующее:

4.1 Действия (Actions или экшены)
Фраза из функции вывелась на сайт ниже футера
Важно! PHP оценивает весь скрипт перед его выполнением. Запись вызовов add_action() в верхней части файла в порядке их выполнения, а затем определение ваших функций в том же порядке ниже, сделает файл более легким для чтения.

Удаление функций из хука действия с помощью remove_action()

Чтобы удалить действие из хука действия, напишите новую функцию remove_action(), а затем вызовите написанную функцию с помощью add_action().

Функция remove_action() также должна содержать как минимум 2 параметра.

// В действие 'init', которое вызывается после завершения загрузки кода ядра WordPress, добавьте функцию 'remove_My_Meta_Tags'.

add_action( 'init', 'remove_My_Meta_Tags' );

// Удалите функцию 'add_My_Meta_Tags' из хука действия wp_head

function remove_My_Meta_Tags()
{
  remove_action( 'wp_head', 'add_My_Meta_Tags');
}

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

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

В следующем примере мы не допустим появления дополнительного текста в футере в статьях, опубликованных в понедельник.

Один из способов сделать это — использовать функцию PHP date() для получения текущего дня, а затем условные теги для проверки того, что сегодня понедельник. После анализа информации страница будет выполнять функцию remove_action() в каждой статье, опубликованной в понедельник.

<?php
// Подцепите действие 'wp_footer', запустите функцию с именем 'mfp_Add_Text()'.

add_action("wp_footer", "mfp_Add_Text");

// Подцепите действие 'wp_head', запустите функцию с именем 'mfp_Remove_Text()'.

add_action("wp_head", "mfp_Remove_Text");

// Определяем функцию с именем 'mfp_Add_Text('), которая просто выводит простой текст методом echo

function mfp_Add_Text()
{
  echo "<p style='color: #FFF;'>After the footer is loaded, my text is added!</p>";
}

// Определяем функцию с именем 'mfp_Remove_Text()', чтобы удалить нашу предыдущую функцию из действия 'wp_footer'

function mfp_Remove_Text()
{
  if (date("l") === "Monday") {

    // удаляем из 'wp_footer' функцию 'mfp_Add_Text' с учетом условия if выше

    remove_action("wp_footer", "mfp_Add_Text");
  }
}

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

Была ли эта страница полезной?