WordPress как на ладони
Недорогой хостинг для сайтов на WordPress: wordpress.jino.ru

add_filter() WP 0.71

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

Фильтры это, своего рода, зацепки внутри кода, через которые можно "отфильтровать" какие-либо данные. Например, в период получения и вывода текста на экран из базы данных, можно "на лету" изменить (отфильтровать) этот текст и вывести на экран уже измененный вариант текста. И благодаря фильтру для этого нам не придется редактировать функцию вывода в файлах движка, а можно подключиться к функции вывода через файл шаблона, использовав заранее предусмотренный разработчиками фильтр.

Функция не делает никаких проверок: существует ли прикрепляемая функция или передается ли название функции в виде строки и т.д.. Сделано это, чтобы add_filter() работала максимально быстро.

Базовый список фильтров смотрите здесь и тут весь список фильтров

О фильтрах и событиях читайте в этой заметке: как работают хуки в WordPress

Основа для: add_action()
1 раз = 0.000015с = очень быстро | 50000 раз = 0.05с = скорость света | PHP 7.0.8, WP 4.7

Хуков нет.

Возвращает

Всегда true.

Использование

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:

add_filter( 'the_content', 'add_text_to_content' );
function add_text_to_content($content){
	$out = $content . "<p>При копировании статьи, ставьте обратную ссылку, пожалуйста!</p>";
	return $out;
}

#2. Изменения блока «подпись картинки» (сaption)

Пример изменения подписи у картинок ([сaption]) под стандарты HTML 5. Функция меняющая контент цепляется на фильтр img_caption_shortcode, который отвечает за преобразование шоткода [сaption] в контенте статьи. Чтобы получить все 3 параметра, передаваемые фильтром, укажем аргумент $accepted_args - 3:

add_filter( 'img_caption_shortcode', 'my_img_caption_shortcode_filter', 10, 3 );
/**
 * Фильтр заменяет шоткод [сaption] под стандарты HTML5
 *
 * @Возвращает HTML текст описывающий тег figure
 **/
function my_img_caption_shortcode_filter( $val, $attr, $content = null ){
	extract(shortcode_atts(array(
		'id'    => '',
		'align' => '',
		'width' => '',
		'caption' => ''
	), $attr));

	if ( 1 > (int) $width || empty($caption) )
		return $val;

	$capid = '';
	if ( $id ) {
		$id = esc_attr($id);
		$capid = 'id="figcaption_'. $id . '" ';
		$id = 'id="' . $id . '" aria-labelledby="figcaption_' . $id . '" ';
	}

	return '<figure ' . $id . 'class="wp-caption ' . esc_attr($align) . '" style="width: '
	. (10 + (int) $width) . 'px">' . do_shortcode( $content ) . '<figcaption ' . $capid 
	. 'class="wp-caption-text">' . $caption . '</figcaption></figure>';
}

#3. Функцию можно передавать как анонимную:

Помните, что невозможно удалить фильтр, объявленный анонимной функцией.

Не используйте анонимную функцию в качестве коллбэк функции, если подразумевается многократное использование фильтра

add_filter( 'the_title', function( $title ){
	return '<b>'. $title. '</b>';
});

#4. Внутри классов функцию фильтра нужно указывать через массив:

Первое значение массива это экземпляр класса, а второе название метода этого класса.

add_filter( 'media_upload_newtab', array( $this, 'media_upload_mycallback') );

Если метод статический, то в первом значении массива нужно указать название класса:

add_filter( 'media_upload_newtab', array( 'My_Class', 'media_upload_mycallback') );

Заметки

  • Global. WP_Hook[]. $wp_filter A multidimensional array of all hooks and the callbacks hooked to them.

Список изменений

С версии 0.71 Введена.

Код add_filter() WP 5.6

<?php
function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
	global $wp_filter;
	if ( ! isset( $wp_filter[ $tag ] ) ) {
		$wp_filter[ $tag ] = new WP_Hook();
	}
	$wp_filter[ $tag ]->add_filter( $tag, $function_to_add, $priority, $accepted_args );
	return true;
}

Из метки: Фильтры (хуки)

Еще из раздела: Хуки: события, фильтры

36 комментов
Полезные 5 Все
    Войти