add_filter с версии 0.71

Описание

Регистрирует хук — цепляет PHP функцию к указанному фильтру.

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

add_filter() используется в: add_action().

Функция возвращает true или false, в зависимости от того удалось или нет добавить функцию к фильтру. Нет никаких проверок на то, существует ли добавляемая функция, передается ли название функции в виде строки и т.д. сделано это для оптимизации функции add_filter(), поэтому все работает максимально быстро.

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

<?php add_filter( $tag, $function_to_add, $priority, $accepted_args ); ?> 

Параметры

$tag (строка) (обязательный)

Название фильтра, для которого будет срабатывать функция определенная в параметре $function_to_add.
По умолчанию: нет

$function_to_add (строка) (обязательный)

Название функции, которая будет срабатывать для указанного в предыдущем параметре фильтра. Название функции нужно указывать в виде строки: 'название_функции'. Для функций внутри классов указываем массив: array('название_класса', 'название_функции'), подробнее читаем тут (знания англ. приветствуются).
По умолчанию: нет

$priority (число)

Приоритет выполнения функций для одного и тоже фильтра. Чем больше число, тем позднее будет выполнятся функция: например, сначала 20 потом 10. Функции с одинаковым приоритетом, будут выполнятся в порядке их добавления к фильтрам.
По умолчанию: 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. Пример изменения блока "подпись картинки" ([ caption]) под стандарты HTML 5. Функция меняющая контент цепляется на фильтр img_caption_shortcode, который отвечает за преобразование шоткода в контенте статьи. Чтобы получить все 3 параметра, передаваемые фильтром, укажем аргумент $accepted_args - 3:

add_filter('img_caption_shortcode', 'my_img_caption_shortcode_filter',10,3);

/**
 * Фильтр заменяет шоткод [ caption] под стандарты 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>';
}

На заметку

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

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

Имейте ввиду, что анонимные функции были введены в PHP 5.3.0.

Для более ранних версий PHP, можно использовать специальную функцию PHP create_function(), но помните, что функции созданные через create_function(), не кэшируются различными PHP оптимизаторами. Поэтому не используйте create_function() в качестве коллбэк функции, если подразумевается многократное использование фильтра или функция фильтра используется в логической модели.

2. Внутри классов фильтры нужно указывать через объект:

<?php add_filter('media_upload_newtab', array(&$this, 'media_upload_mycallback')); ?>

add_filter()

function add_filter($tag, $function_to_add, $priority = 10, $accepted_args = 1) {
	global $wp_filter, $merged_filters;

	$idx = _wp_filter_build_unique_id($tag, $function_to_add, $priority);
	$wp_filter[$tag][$priority][$idx] = array('function' => $function_to_add, 'accepted_args' => $accepted_args);
	unset( $merged_filters[ $tag ] );
	return true;
}

Ещё из раздела

Смотрите также: Функции WordPress и Теги Шаблона.

Многие манимейкеры в рунете используют биржи вечных ссылок для наращивания тИЦ. тИЦ и позиции запросов в выдаче зачастую совершенно не связаны. Если вам нужны посетители, не гонитесь за тИЦ, ибо он не играет никакой роли для этого!