Как использовать фильтры в WordPress
Фильтры WordPress меняют данные через подключенные PHP-функции. Вы привяжете обработчик к заголовку записи, увидите результат на странице, снимете обработчик и создадите собственный хук для плагина. Код можно разместить в functions.php дочерней темы или в собственном плагине, поэтому ядро и чужие файлы останутся без изменений.
Что такое WordPress-фильтр
Фильтр – именованный хук, через который WordPress пропускает значение. Разработчик подключает к нему callback, который получает значение, меняет его и возвращает результат.
Хук the_title меняет выводимый заголовок публикации. Заголовок в базе данных при этом не меняется. Если обработчиков несколько, каждый получает результат предыдущего.
Функция-фильтр обязана вернуть значение через return. Если возврат забыть, PHP вернет null, и заголовок или контент может исчезнуть из вывода.
Действие, или action, запускает код в определенный момент работы WordPress. Обработчик действия может зарегистрировать шорткод или отправить уведомление. WordPress не использует возвращаемое значение action для замены фильтруемых данных.
Подробное описание механизма ищите в справочнике разработчика WordPress.
Используем фильтры в WordPress
Размещайте примеры в functions.php дочерней темы или в собственном плагине. Дочерняя тема подходит для изменений, связанных с оформлением сайта, а плагин сохраняет обработчики при смене темы.
Не редактируйте ядро WordPress, родительскую тему или файлы чужого плагина. Обновление перезапишет такие изменения. Перед экспериментом сохраните копии файлов и работайте на тестовой копии сайта.
Если дочерней темы нет, создайте учебный плагин через файловый менеджер хостинга или SFTP:
- Создайте каталог
wp-content/plugins/filter-demo. - Создайте в нем файл
filter-demo.php. - Добавьте в файл код плагина и сохраните его.
<?php
/*
Plugin Name: Filter Demo
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}В панели WordPress откройте «Плагины» → «Установленные» и активируйте Filter Demo. Добавляйте следующие PHP-фрагменты в конец этого файла.
В functions.php вставляйте код внутри существующего PHP-блока. Не добавляйте туда заголовок Plugin Name. Для отката деактивируйте Filter Demo или удалите добавленные фрагменты из дочерней темы.
Создаем функцию и прикрепляем ее к фильтру
Учебный обработчик удаляет гласные из заголовка записи. Хук the_title передает заголовок и ID публикации, поэтому callback принимает два аргумента.
function remove_the_vowels( $title, $post_id ) {
if ( is_admin() || ! is_singular( 'post' ) ) {
return $title;
}
if ( ! in_the_loop() || ! is_main_query() ) {
return $title;
}
if ( (int) $post_id !== (int) get_queried_object_id() ) {
return $title;
}
$filtered_title = preg_replace( '/[aeiouаеёиоуыэюя]/iu', '', $title );
return null === $filtered_title ? $title : $filtered_title;
}
add_filter( 'the_title', 'remove_the_vowels', 20, 2 );Регулярное выражение удаляет латинские и русские гласные без учета регистра. Модификатор u включает обработку строки как UTF-8. Выражение /[aeiou]/i удаляет только латинские гласные, поэтому русское слово с ним не изменится.
Хук the_title срабатывает в меню, виджетах и других местах вывода. Условия в примере оставляют обработку только для заголовка текущей записи в главном цикле.
Функция add_filter() принимает имя хука, callback, приоритет и количество аргументов. Параметры удобно сопоставить в одной таблице.
| Параметр | Что означает | Где используется |
|---|---|---|
$hook_name | Имя хука, например the_title | Первый аргумент add_filter(), remove_filter() и apply_filters() |
$callback | Функция или другой вызываемый обработчик | Второй аргумент add_filter() и remove_filter() |
$priority | Порядок выполнения callback: меньшее число запускается раньше | Третий аргумент add_filter() и remove_filter() |
$accepted_args | Количество аргументов, которые получает callback | Четвертый аргумент add_filter() |
$value | Исходное фильтруемое значение | Второй обязательный аргумент apply_filters() |
...$args | Дополнительные данные для контекста | Аргументы после $value в apply_filters() |
В примере приоритет равен 20, поэтому callback запускается после обработчиков с приоритетом 10. Аргумент $accepted_args равен 2, поэтому функция получает заголовок и ID, если сам хук передает оба значения.
Откройте отдельную запись с заголовком «Пример записи» в обычном шаблоне главного цикла. На странице появится «Прмр зпс», а в редакторе сохранится исходный заголовок.
Если результат не изменился, очистите кеш страницы. Регистрацию можно проверить временным вызовом:
var_dump( has_filter( 'the_title', 'remove_the_vowels' ) );Функция has_filter() вернет приоритет 20, а при отсутствии callback – false. Проверка подтверждает регистрацию, но не заменяет просмотр результата на странице. После проверки удалите диагностическую строку.
Callback может быть анонимной функцией или методом класса. Метод объекта подключают через array( $this, 'method' ). Анонимную функцию нельзя снять по придуманному строковому имени: сохраните тот же объект замыкания.
Удаляем фильтр
Функция remove_filter() снимает конкретный callback с хука. Имя хука, callback и приоритет должны совпадать с данными регистрации. Callback можно снять только после подключения и до вызова фильтра.
В учебном плагине обработчик подключается во время загрузки файла. Снимите его на init с приоритетом 100:
function filter_demo_remove_title_filter() {
remove_filter( 'the_title', 'remove_the_vowels', 20 );
}
add_action( 'init', 'filter_demo_remove_title_filter', 100 );После обновления страницы заголовок снова отобразится полностью. Приоритет 100 относится к действию init, а число 20 – к снимаемому callback.
Для чужого плагина или темы найдите строку add_filter(). Возьмите из нее имя хука, callback и приоритет, затем подключите снятие позже регистрации.
Например, тема подключает callback на after_setup_theme с приоритетом 10. Снимите его на том же действии с приоритетом 20:
function filter_demo_remove_theme_title_filter() {
remove_filter( 'the_title', 'theme_title_callback', 10 );
}
add_action( 'after_setup_theme', 'filter_demo_remove_theme_title_filter', 20 );В этом примере значение 10 у remove_filter() совпадает с приоритетом, который тема указала при регистрации theme_title_callback. Число 20 у add_action() запускает снятие позже регистрации. При несовпадении WordPress оставит обработчик.
Проверить снятие можно в том же callback действия:
$removed = remove_filter( 'the_title', 'remove_the_vowels', 20 );
var_dump( $removed );
var_dump( has_filter( 'the_title', 'remove_the_vowels' ) );При успешном первом снятии значения будут true и false. Повторный вызов вернет false, если callback уже снят. Диагностический вывод удалите после проверки.
Анонимную функцию снимают через тот же объект замыкания и тот же приоритет:
$title_callback = function ( $title ) {
return $title;
};
add_filter( 'the_title', $title_callback, 20 );
remove_filter( 'the_title', $title_callback, 20 );Функция remove_all_filters() удаляет все обработчики указанного хука. Первый параметр задает имя хука, а второй необязательный параметр задает приоритет.
// Снять обработчики the_title с приоритетом 20.
remove_all_filters( 'the_title', 20 );
// Снять обработчики the_title со всех приоритетов.
remove_all_filters( 'the_title' );Не используйте remove_all_filters() без точной причины: функция отключит обработчики темы и других плагинов. Для выборочного изменения оставьте remove_filter().
Создаем свой собственный фильтр
Функция apply_filters() создает точку изменения данных в вашем коде. Первый аргумент $hook_name задает имя хука, под которым подключаются callback. Он не обозначает имя вызываемой функции.
Добавьте эту функцию в собственный плагин Filter Demo:
function peter_griffin_quote() {
$quote = "The bird is the word.";
return apply_filters( 'peter_griffin_quote', $quote );
}Функция возвращает строку после прохождения через все подключенные обработчики. Без callback apply_filters() вернет исходное значение $quote.
Другой разработчик сможет изменить строку из дочерней темы, не редактируя файл плагина:
function change_the_quote( $quote ) {
$quote = str_replace( 'bird', 'nerd', $quote );
return $quote;
}
add_filter( 'peter_griffin_quote', 'change_the_quote' );Добавьте callback в functions.php активной дочерней темы. Для собственного проекта используйте уникальный префикс в имени функции и хука, чтобы снизить риск конфликтов.
Чтобы увидеть строку на странице, добавьте в учебный плагин шорткод:
function filter_demo_quote_shortcode() {
return esc_html( peter_griffin_quote() );
}
add_shortcode( 'filter_demo_quote', 'filter_demo_quote_shortcode' );Создайте тестовую страницу и вставьте [filter_demo_quote] в блок «Шорткод». В предпросмотре появится «The nerd is the word.». Если убрать внешний callback, страница покажет «The bird is the word.».
Дополнительные аргументы передают контекст, например ID записи или язык сообщения. Callback возвращает одно изменяемое значение, а контекст получает через параметры, указанные в add_filter().
Для отката удалите внешний callback и блок шорткода со страницы. Затем деактивируйте Filter Demo, если он больше не нужен.
Как выбрать функцию для работы с фильтром
- Используйте
add_filter(), чтобы изменить значение существующего хука. - Используйте
remove_filter(), чтобы отключить конкретный callback с известными именем и приоритетом. - Используйте
apply_filters(), чтобы разрешить другим разработчикам менять данные вашего плагина.
Совет от нашей редакции: сохраняйте именованные callback для изменений, которые планируете отключать. Так проще найти регистрацию, проверить приоритет и снять нужную функцию.
Популярное за неделю
- Как создать сайт самому в 2026: 4 способа + пошаговая инструкция 34 мин чтения
- Лучшие конструкторы для создания сайтов — плюсы, минусы и сравнения 22 мин чтения
- Как правильно редактировать шаблоны WordPress 4 мин чтения
- Как отредактировать главную страницу WordPress 11 мин чтения
- Как увеличить размер файла в WordPress 12 мин чтения
- Как настроить SMTP в WordPress: проверка и установка 2 мин чтения
Комментарии
Очень просто написано. Все понятно. Спасибо!
Все блин пишут как весело и легко работать с фильтрами!
ААААА СКАЖИТЕ БЛИН ХОТЬ ОДИН, В КАКОЙ ФАЙЛ ИХ ДОПИСЫВАТЬ??????
в fUNKTION.PHP или куда????
Можно писать в любом php файле.
Но советую в function.php.
Спасибо! Очень интересно и доступно!