4.2 Фильтры (Filters)

Фильтры — один из двух типов Хуков (hooks).

Они дают возможность функциям изменять данные других функций. Они являются аналогом действий (Action-ов).

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

Добавить фильтр

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

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

Вы будете использовать функцию add_filter(), передавая как минимум два параметра, string $tag, вызываемую $function_to_add.

Пример ниже будет запущен при выполнении the_title.

<?php
function wporg_filter_title($title)
{
return 'The ' . $title . ' was filtered';
}
add_filter('the_title', 'wporg_filter_title');

Допустим, у нас есть заголовок публикации «Learning WordPress», в приведенном выше примере он будет изменен на «The Learning WordPress was filtered».

Этот блок имеет неожидаемое или неверное содержимое.

Попытка восстановления блока

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

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

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

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

Подробное объяснение этих параметров можно найти в статье о действиях.

Пример

Добавление класса CSS к тегу при выполнении определенного условия:

<?php
function wporg_css_body_class($classes)
{
if (!is_admin()) {
$classes[] = 'wporg-is-awesome';
}
return $classes;
}
add_filter('body_class', 'wporg_css_body_class');

Фильтер (filter) — это функция PHP, вызываемая определенным хуком filter, которая изменяет данные, возвращаемые существующими функциями. Как и хуки действий, хуки фильтров также зависят от контекста.

Полный список хуков фильтров и контекстов, в которых они вызываются, доступен на странице Справочник фильтров плагинов WordPress.

Добавление фильтров с помощью функции add_filter()

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

// Подцепите хук фильтра 'the_content' (содержимое любой статьи), запустите функцию с именем 'mfp_Fix_Text_Spacing'.

add_filter("the_content", "mfp_Fix_Text_Spacing");

// Автоматическое исправление двойных пробелов в любой записи

function mfp_Fix_Text_Spacing($the_Post)
{
 $the_New_Post = str_replace("  ", " ", $the_Post);
 return $the_New_Post;
}

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

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

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

Пример плагина для изменения отрывка поста

В WordPress есть функция для получения отрывков постов, которая называется get_the_excerpt(). Это также хук фильтра. Добавление этого фильтра после получения отрывка изменит текст до того, как он будет отображен на сайте WordPress.

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

Поскольку возвращаемым значением функции get_the_excerpt() является фактический текст отрывка, плагин будет автоматически вводить новое значение в качестве параметра функции $old_Excerpt при вызове с помощью add_filter(). Функция, определяемая плагином, должна возвращать новое значение.

<?php
/*
Plugin Name: Add Excerpt 
*/
// Подцепите хук фильтра get_the_excerpt, запустите функцию mfp_Add_Text_To_Excerpt

add_filter("get_the_excerpt", "mfp_Add_Text_To_Excerpt");

// Берем отрывок, добавляем перед ним текст и возвращаем новый отрывок

function mfp_Add_Text_To_Excerpt($old_Excerpt)
{
  $new_Excerpt = "<b>Excerpt: </b>" . $old_Excerpt;
  return $new_Excerpt;
}

Удаление фильтров с помощью remove_filter()

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

В следующем примере мы удалим дополнительный текст отрывка, если текущий день — четверг. Мы будем использовать функцию remove_filter() как минимум с двумя параметрами.

Первый параметр должен содержать хук фильтра, к которому привязана функция. Второй параметр должен быть именем фильтра, который вы хотите удалить. Добавьте параметр приоритета, если вы определили его при создании функции.

// Перехватите хук фильтра get_the_excerpt, запустите функцию с именем mfp_Add_Text_To_Excerpt.

add_filter("get_the_excerpt", "mfp_Add_Text_To_Excerpt");

// Если сегодня четверг, удалите фильтр из the_excerpt()

if (date("l") === "Thursday") {
  remove_filter("get_the_excerpt", "mfp_Add_Text_To_Excerpt");
}

// Возьмите отрывок, добавьте перед ним текст и верните новый отрывок

function mfp_Add_Text_To_Excerpt($old_Excerpt)
{
  $new_Excerpt = "<b>Excerpt: </b>" . $old_Excerpt;
  return $new_Excerpt;
}

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

Важно! Использование тестового сайта WordPress для тестирования новых плагинов поможет вам избежать ошибок, которые могут привести к простою. Существует два способа создания среды тестирования — вручную или с помощью плагина, например, WP Staging. В качестве альтернативы установите WordPress локально на свой компьютер.

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