Плагины WordPress PHP (хуки, фильтры, действия)
В прошлом занятии мы уже упоминали о хуках, давайте рассмотрим их подробнее.
Хуки (от анг. слова hook — крючок, зацепка) — это созданные пользователями функции (то есть нами), которые привязываются к функциям WordPress (заложены в самом коде движка WordPress). То есть при каждом выполнении функции движка будет проверяться — не привязана ли к этой функции какая-нибудь пользовательская функция и если таковая есть, то одновременно с функцией движка будет выполнена пользовательская функция.
Получается как будто бы некий симбиоз нашей функции с функцией движка, который приводит к увеличению функциональности WordPress, но при этом хуки не изменяют код файлов ядра (код движка WordPress). Вмешательство в код движка может создать брешь в системе безопасности сайта, а также при каждом очередном обновлении версии WordPress все бы наши модификации ядра исчезали.
Хуками в WordPress называются фильтры (filter) и события (action). В программной части это абсолютно одно и тоже, т.е. обрабатывается и то и другое одинаково, можно например заменять функции add_filter() и add_action() — все будет работать! Разделение нужно, потому что по смыслу это разные вещи
Фильтры (filters) предназначены для “фильтрования” (изменения) любых данных перед тем как они будут выведены на странице или добавлены для хранения в базу данных. Это фильтрация спама, ошибок или просто ошибочного ввода в формах, откуда собственно и произошло английское название.
Действия (actions) предназначены для замены различных действий ядра вашими действиями (например изменения строки запроса к базе данных), в программировании такое изменение действий базового функционала ещё называют перегрузкой.
Как работают фильтры в WordPress
Для работы фильтра используются две функции:
- apply_filters() — вызывается там, где применяется фильтр. Запускает добавленные к фильтру PHP функции.
- add_filter() — добавляет/прикрепляет PHP функции к указанному фильтру. Используется до того, как фильтр будет применен/вызван/запущен с помощью apply_filters(). Нужно это для того, чтобы, во время срабатывания фильтра, PHP функция уже была подключена к фильтру и обработала переданное значение (отфильтровала его).
apply_filters()
Применяет прикрепленную к указанному фильтру PHP функцию. Прикрепляется функция с помощью add_filter().
Используется там, где нужно изменить значение переменной (например текст).
Используется в плагинах и темах, для создания хуков-фильтров (зацепок пользовательских функций).
Новые фильтры должны иметь уникальные названия и не должны совпадать с уже имеющимися в WP названиями фильтров.
Возвращает
Отфильтрованное значение $value, которое передается функции-обработчику хука.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
<?php
apply_filters( $tag, $value, $var ... );
$tag(строка) (обязательный)
Названиефильтра.
Поумолчанию: нет
$value(строка/массив/число/объект/логический) (обязательный)
Значение, которое будет передаваться функции в её первом аргументе, другими словами — значение, которое нужно отфильтровать.
Поумолчанию: нет
$var(строка/массив/число/объект/логический)
Дополнительныезначения, которые будет передавать фильтр функции.
Поумолчанию: нет
?>
|
|
1
2
3
4
5
6
7
|
<?php
$myvar = apply_filters( $tag, $value );
$myvar = apply_filters( $tag, $value, $var1, $var2, ... );
add_filter()
?>
|
Прикрепляет указанную PHP функцию к указанному хукe-фильтру. Так, во время срабатывания фильтра значение будет обработано указанной PHP функцией.
Фильтры это, своего рода, зацепки внутри кода, через которые можно «отфильтровать» какие-либо данные. Например, в период получения и вывода текста на экран из базы данных, можно «на лету» изменить (отфильтровать) этот текст и вывести на экран уже измененный вариант текста. И благодаря фильтру для этого нам не придется редактировать функцию вывода в файлах движка, а можно подключиться к функции вывода через файл шаблона, использовав заранее предусмотренный разработчиками фильтр.
add_filter() не делает никаких проверок: существует ли прикрепляемая функция или передается ли название функции в виде строки и т.д.. Сделано это, чтобы add_filter() работала максимально быстро.
Базовый список фильтров смотрите на: https://codex.wordpress.org/Plugin_API/Filter_Reference
true или false, в зависимости от того удалось или нет добавить новый фильтр.
|
1
2
3
|
<?php
add_filter( $tag, $function_to_add, $priority, $accepted_args );
?>
|
$tag(строка) (обязательный)
Название фильтра, для которого будет срабатывать функция определенная в параметре $function_to_add.
По умолчанию: нет
$function_to_add(строка) (обязательный)
Название функции, которая будет срабатывать для указанного в предыдущем параметре фильтра. Название функции нужно указывать в виде строки: ‘название_функции’. Для функций внутри классов указываем массив: array(‘название_класса’, ‘название_функции’)
По умолчанию: нет
$priority(число)
Приоритет выполнения функций для одного и того же фильтра. Чем больше число, тем позднее будет выполнятся функция: например, сначала 10 потом 20. Функции с одинаковым приоритетом, будут выполнятся в порядке их добавления к массиву фильтров.
По умолчанию: 10
$accepted_args(число)
Количество аргументов передаваемых фильтром функции. Некоторые фильтры могут передавать больше чем 1 аргумент, допустим — 2, для таких случаев нужно указывать 2 в этом параметре.
По умолчанию: 1
Пример использования фильтров
#1. Обычный пример, показывающий как можно добавить любую надпись в конец каждой статьи, через фильтр the_content:
|
1
2
3
4
5
6
7
8
|
<?php
add_filter(‘the_content’, ‘add_text_to_content’);
function add_text_to_content($content){
$out = $content . «<p>При копировании статьи, ставьте обратную ссылку, пожалуйста!</p>»;
return $out;
}
?>
|
Фильтров в WordPress много и вы наверняка с ними встречались в темах и плагинах. Одни из самых популярных это: the_content, body_class, sanitize_user, comment_form и т.д.
События
Как работают события в WordPress
События или действия (actions) в WordPress очень похожи на события в JavaScript. Событие выполняется вызовом функции do_action(), а добавить функцию к любому событию можно с помощью функции add_action().
Для работы события используются две функции:
- do_action() — это и есть событие. Запускает/вызывает добавленные к событию функции. Вызывается там, где должно сработать событие.
- add_action() — добавляет/прикрепляет функции к событию, которое вызывается с помощью do_action(). Функция должна прикрепляться к событию до того, как событие произойдет. Нужно это, чтобы во время срабатывания события PHP функции уже были прикреплены к событию.
do_action()
Создает событие (зацепку для произвольной функции). Чтобы функция сработала в момент события её нужно подключить к этому событию с помощью функции add_action().
|
1
2
3
|
<?php
do_action( $tag, $arg );
?>
|
Функции можно передавать бесконечное множество аргументов:
do_action( $tag, $arg_a, $arg_b, … );
$tag(строка) (обязательный)
Название создаваемого хука.
По умолчанию: нет
$arg(строка/массив/число/объект/логический) Значение аргумента(ов), который будет передаваться через хук. Действия отличаются от фильтров, тем что передаваемые действием данные, не возвращаются обратно в функцию и не используются там в дальнейшем, а всего-лишь передаются для использования в функции хука.
add_action()
Регистрирует хук-событие. При регистрации указывается PHP функция, которая сработает в момент события, которое вызывается с помощью do_action().
Хук на который цепляется функция добавляется с помощью функции do_action().
Действия (actions), в отличии от фильтров (add_filter()), нужны, чтобы выполнить какое-либо действие в нужный момент, тогда как фильтры передают и получают обратно данные, которые затем используются.
false или true, в зависимости от того удалось ли зарегистрировать хук.
|
1
2
3
|
<?php
add_action( $tag, $function_to_add, $priority, $accepted_args );
?>
|
$tag(строка) (обязательный)
Название действия, к которому будем цеплять функцию.
По умолчанию: нет
$function_to_add(строка/колбэк) (обязательный)
Название функции, которая должна быть вызвана во время срабатывания действия, т.е. функция которую цепляем к хуку. Формат передачи функции — обычно строк.
По умолчанию: нет
$priority(число)
Приоритет выполнения функции. Если на этот же хук «прицеплены» еще функции, то приоритет будет решать последовательность их выполнения. Меньше число — раньше выполняется, т.е. 10 будет выполняться раньше чем 20.
По умолчанию: 10
$accepted_args(число)
Число аргументов, которые принимает функция. Разумеется действие должно передавать это число аргументов.
По умолчанию: 1
Будем отправлять письмо друзьям, при публикации нового поста:
|
1
2
3
4
5
6
7
8
9
10
|
<?php
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’ );
return $post_ID;
}
add_action(‘publish_post’, ’email_friends’);
?>
|
Точно так же можно зарегистрировать этот хук через add_filter():
add_filter(‘publish_post’, ’email_friends’);
При выполнении события или действия, выполняются все функции, добавленные к событию в определенном порядке. Это легче всего понять с помощью простого примера. Определяем три функции, которые будут выводить 1, 2 и 3 соответственно:
|
1
2
3
4
5
|
<?php
function one() { echo 1; }
function two() { echo 2; }
function three() { echo 3; }
?>
|
Добавляем функции к событию foo с помощью функции add_action():
|
1
2
3
4
5
|
<?php
add_action( ‘foo’, ‘one’ );
add_action( ‘foo’, ‘two’ );
add_action( ‘foo’, ‘three’ );
?>
|
И выполняем наше событие с помощью функции do_action():
do_action( ‘foo’ ); // выведет 123
Первый аргумент к функциям — это строка foo — название события. Название может быть любым, но во избежание конфликтов с другими плагинами и темами в собственных событиях лучше использовать префикс, например myplugin_foo, где myplugin это название вашего плагина.
Второй аргумент к функции add_action() — это функция, которая вызывается в момент выполнения события. Функции в рамках одного события выполняются в том же порядке, в котором они были добавлены к событию, за исключением когда функция добавляется к событию с повышенным или пониженным приоритетом.
Итак, наш пример вызовет функции one(), two() и three() по порядку, что выведет на экран 123. Конечно мы могли самостоятельно вызвать эти функции в этом же порядке на месте do_action(), что дало бы тот же самый результат. Так зачем использовать события?
Зачем использовать события
Любой другой плагин или тема смогут легко добавить или удалить функции из вашего события без необходимости изменять код вашего плагина. Такой подход делает ваш плагин более гибким. Например:
|
1
2
3
4
5
6
7
|
<?php
/* В другом плагине */
function four() { echo 4; }
remove_action( ‘foo’, ‘three’ );
add_action( ‘foo’, ‘four’ );
?>
|
Таким образом, когда дело дойдет до вызова события foo в вашем плагине, на экран выведется уже не 123, а 124, поскольку другой плагин удалил функцию three() из вашего события с помощью функции remove_action(), и добавил на ее место новую функцию four().
Пример с выводом чисел не самый полезный. На практике достаточно легко придумать события в вашей теме или в плагине, которые могли бы быть полезными для других плагинов, например:
Ваша тема может выполнить событие в момент вывода шапки, и любой плагин сможет вывести на этом месте баннер, не изменяя код вашей темы
Ваша тема может выполнить событие в подвале, и с помощью плагина можно будет вставить в подвал любой текст
Ваш плагин выводит блок «поделиться» в конце каждой статьи, другой плагин сможет добавить новую социальную сеть в этот же блок
Стоит так же отметить, что в самом ядре WordPress есть более 1500 фильтров и событий, которые можно использовать в темах и плагинах.