Руководство: все о хуках в WordPress
Вам когда-нибудь говорили, что решение вашей проблемы заключается в том, что вам нужно «зацепиться» за что-то, чтобы делать свое дело или использовать, add_filterне понимая, почему это все портит? Хуки составляют основу WordPress и предоставляют темам и плагинам способ взаимодействия или изменить код В этом посте мы разберем, что такое хуки, как они работают и как мы можем их использовать.
Что такое крючки?
По мере того, как WordPress выполняет свой код (на всем пути от начала загрузки классов, загрузки плагинов, загрузки темы, создания запроса для текущего запроса и, наконец, рендеринга HTML), он проходит через кучу «контрольных точек»; крючки. При обнаружении хука WordPress останавливает свою работу и проверяет, есть ли какие-либо функции (в теме, плагине или самом WordPress), которые зарегистрированы для запуска на этом хуке. Если есть, WordPress запустит все эти функции, а затем продолжит с того места, где остановился.
Это позволяет плагинам, темам и самому WordPress «цепляться» за определенные точки, чтобы добавлять, например, таблицы стилей в <head>тег темы, изменять то, как WordPress запрашивает сообщения, или просто изменять содержимое сообщения, если это необходимо.
Есть два типа крючков; действия и фильтры. Они работают очень похоже друг на друга, но с одним исключением, которое мы рассмотрим ниже.
Действия и фильтры
Чтобы подключиться к действию или фильтру, вам нужно определить, какой хук (по его имени) вы хотите использовать, и определить обратный вызов — имя функции, которую вы хотите запустить. В большинстве случаев хуки предоставляют параметры или переменные, относящиеся к хуку.
Действия — это просто «контрольные точки» в выполнении WordPress, где вы можете выполнить задачу или повторить что-то. В некоторых редких случаях вы можете изменить объект (указанный в параметрах), чтобы все последующее выполнение работало с этим измененным объектом.
Фильтры предназначены для изменения переменной или вывода. Все обработчики фильтров предоставляют переменную, которую вы можете изменить, в качестве первого параметра и позволяют вам изменить ее или вернуть что-то другое.
В WordPress работает множество хуков, но вы можете создать свои собственные в своем плагине или теме. Это позволяет разработчикам расширять и изменять ваш код; например, изменение плагина через тему или изменение родительской темы через дочернюю тему.
Многие функции WordPress, обычно используемые для распечатки сообщений, также являются фильтрами или действиями. Например, функция the_title()выводит заголовок сообщения, но это также и фильтр.
Давайте посмотрим, как мы цепляемся за них на практике.
Привязка к действиям
Чтобы зацепиться за действие, вы используете метод add_action(). Как минимум требуется два параметра; имя хука и обратный вызов; имя функции, которую вы хотите запустить. При желании вы можете указать приоритет в качестве третьего параметра и определить количество аргументов, которые будут переданы вашей функции обратного вызова. Мы рассмотрим два необязательных параметра позже, а пока приведем пример add_action:
add_action('init', 'my_function_name');
function my_function_name() {
// Do your stuff
}Первый параметр to add_action— это имя действия; в этом случае initэто довольно распространенный хук WordPress, который происходит во время инициализации. Второй параметр — это ваш обратный вызов, в данном случае имя функции, которую мы хотим запустить. Затем все, что вам нужно сделать, это определить функцию с таким именем и добавить в нее свой код.
Вы также можете использовать анонимные функции, в которых вы определяете функцию внутри add_actionвместо предоставления имени функции, например:
add_action('init', function() {
// Do your stuff
});Многие разработчики предпочитают этот метод, поскольку он предотвращает риск переопределения функции PHP с тем же именем.
Если вам нужно запустить функцию, определенную внутри класса PHP, вам нужно предоставить массив в качестве параметра обратного вызова; где первый элемент — это объект класса, а второй элемент — имя функции:
class MyClass {
public function __construct() {
add_action('init', [$this, 'myFunctionName']);
}
public function myFunctionName() {
// Do your stuff
}
}Подключаемся к фильтрам
Чтобы подключиться к фильтру, вы используете функцию add_filter(). Аналогично действиям выше, первый параметр — это имя фильтра, а второй — ваш обратный вызов. При желании вы можете указать приоритет в качестве третьего параметра и количество аргументов в качестве четвертого. Вот пример add_filter:
add_filter('the_title', 'my_function_name');
function my_function_name($title) {
// Do your stuff
return $title;
}В приведенном выше примере мы подключаемся к фильтру the_title(который выводит заголовок сообщения) и приказываем WordPress запустить нашу функцию. Все фильтры всегда будут предоставлять один аргумент; переменная для изменения. В моей функции я назвал его $title, так как знаю, что он содержит заголовок сообщения. Внутри функции я могу изменить ее или полностью переопределить переменную. Важно помнить, что в фильтрах всегда нужно возвращать переменную. Если вы ничего не возвращаете в своей функции обратного вызова, переменная пуста. Если бы я пропустил оператор return в приведенном выше примере, заголовки сообщений нигде не отображались бы.
Переменный аргумент и правило возврата чего-либо в вашей функции обратного вызова — практически единственное различие между фильтрами и действиями. Все остальное работает так же. Вы можете следовать примерам для анонимных функций и классов, показанных выше для действий для фильтров, а также необязательных параметров приоритета и количества аргументов; которые мы рассмотрим далее.
приоритет
Третий (необязательный) параметр add_actionи add_filterпредставляет собой целое число, определяющее приоритет вашей функции обратного вызова. Это полезно в тех случаях, когда есть несколько функций (не обязательно от вас в вашей теме или плагине, помните, что сам WordPress использует свои собственные хуки), и вам нужно решить, какую из них запустить первой.
Если приоритет не указан, по умолчанию он равен 10. Чем ниже приоритет, тем раньше он запускается, а чем выше приоритет, тем позже он запускается. Вы не можете указать отрицательный приоритет.
Представьте себе несколько функций обратного вызова, зарегистрированных в init. Если для нескольких обратных вызовов не был указан приоритет, WordPress будет запускать их в том порядке, в котором они были найдены (например, в functions.phpкоде вашего плагина).
add_action('init', 'my_function_name');
add_action('init', 'my_second_function_name');
add_action('init', 'my_third_function_name', 12);
add_action('init', 'my_fourth_function_name', 1);Это будет порядок, в котором WordPress будет запускать вышеуказанные обратные вызовы:
my_fourth_function_name(приоритет 1)my_function_name(приоритет 10)my_second_function_name(приоритет 10, но появляется позже в коде)my_third_function_name(приоритет 12)
Количество аргументов
Обычно хуки предоставляют некоторые дополнительные данные, которые важны и полезны для функций обратного вызова. Например, действие save_post(выполняется всякий раз, когда сообщение обновляется) предоставляет два возможных аргумента; идентификатор сообщения и объект сообщения. Они полезны для операций, которые вам обычно нужно запускать на этом хуке (например, если вы хотите сохранить метаданные поста, вам нужен идентификатор поста).
Если для действия или фильтра не было указано количество аргументов, по умолчанию он равен 1. Вот почему вам не нужно определять 1 add_filterдля доступа к переменной, к которой подключен фильтр. Однако действия не могут передавать аргументы, даже если количество аргументов установлено равным 1 по умолчанию.
Давайте рассмотрим пример определения количества аргументов и того, как мы получаем к ним доступ в нашей функции обратного вызова:
add_action('save_post', 'my_function_name', 10, 2);
function my_function_name($post_id, $post) {
// Do your stuff
}В приведенном выше примере мы говорим WordPress передать два аргумента нашей функции обратного вызова. Помните, что нам нужно определить приоритет как третий параметр, поэтому обычно мы определяем значение по умолчанию, равное 10. Что касается нашей функции обратного вызова, теперь мы можем определить те же числовые аргументы, которые мы запрашивали, в приведенном выше примере было 2.
Если бы в приведенном выше примере мы установили количество аргументов равным 1, то был бы заполнен только первый аргумент в нашей функции обратного вызова. Второй, $post, будет неопределенным.
Что делать, если нам нужны данные, которые не были переданы в хук?
Разработчик, создавший хук, полностью определяет, какие аргументы можно передавать. Это означает, что вы не можете просто указать, какие аргументы вам нужны или нужны в вашем add_actionили add_filter. К счастью, в большинстве случаев у нас есть альтернативы для получения необходимых нам переменных. Если вы подключаетесь к действию или фильтру, где, как вы знаете, должны быть определены определенные глобальные переменные, вы можете получить доступ к этим глобальным переменным в своей функции обратного вызова. Кроме того, в WordPress есть целый ряд условных тегов, которые вы можете использовать в своих перехватываемых функциях (за исключением самых ранних перехватов, которые появляются до того, как WordPress определит эти условные теги).
Давайте рассмотрим пример доступа к глобальным переменным. Фильтр the_titleпредоставляет идентификатор сообщения в качестве необязательного аргумента, к которому мы можем получить доступ, определив его как допустимый аргумент;
add_filter('the_title', 'my_function_name', 10, 2);
function my_function_name($title, $post_id) {
if ($post_id == 1) {
return 'First post ever!';
}
return $title;
}Однако мы можем добиться того же результата с помощью;
Если вы знаете, что глобальная переменная определяется точкой запуска хука, вы можете определить их как глобальные в своей функции обратного вызова и получить доступ к данным оттуда. Например, определение global $wp_queryв приведенном выше примере также даст вам доступ к полному объекту wp_query внутри обратного вызова вашей функции.
Условные теги WordPress чрезвычайно полезны. Если вы не зацепились за хук, который происходит очень рано при выполнении WordPress, они доступны. Существуют условные теги для проверки того, на какой странице (шаблоне) вы находитесь, находитесь ли вы внутри меню или цикла сообщений и многое другое. Например, при изменении почтового запроса с помощью хука pre_get_postsочень полезно убедиться, что ваш код работает только в определенных случаях. Например;
add_action('pre_get_posts', 'my_function_name');
function my_function_name($query) {
if (!is_admin()) {
// Do your stuff
}
}Поскольку хук pre_get_postsзапускается как в админке, так и во внешнем интерфейсе, мы можем использовать условный тег, чтобы гарантировать, что наш код влияет только на запрос внешнего интерфейса.
Создание собственных крючков
Вы можете определить свои собственные действия и фильтры. Если вы являетесь разработчиком темы или плагина, вам рекомендуется сделать это, чтобы позволить другим изменять ваш код без изменения исходного кода.
Зарегистрируйте действие с помощью do_action()и зарегистрируйте фильтр с помощью apply_filters().
Требуется минимум 1 do_action()параметр; имя хука. Имейте в виду, что имя хука должно быть уникальным (не называйте его, например init, так как это основной хук WordPress). Поместите do_action()туда, где вы хотите, чтобы крючок появился. Например, вы можете разместить хук в вашей теме header.phpсразу после body, чтобы определить хук, куда разработчики могут выводить скрипты или другой контент.
Вы можете добавить столько параметров, do_actionсколько хотите, после имени хука. Постарайтесь помнить о том, какие данные потребуются разработчикам в ваших ловушках, которые в противном случае не были бы легко доступны.
Требуется минимум 2 apply_filters()параметра; имя хука и переменная, для которой вы регистрируете фильтр. Например, ваша тема может зарегистрировать фильтр вокруг некоторых классов HTML, чтобы разработчики могли изменять или добавлять к ним:
Как и в случае с действиями, вы можете добавить любое количество параметров apply_filtersпосле двух обязательных параметров.
Заключение и полезные ресурсы
Я надеюсь, что благодаря этому вы достигли четкого понимания того, как WordPress выполняет большую часть своего кода, как вы можете изменять код и как вы, как разработчик, можете позволить другим разработчикам также вносить изменения в ваш код.