apply_filters_ref_array

Выполняет функции прикрепленные к указанному хуку (фильтру). Параметры передаются в массиве. Позволяет передать параметр по ссылке.

Эта функцию такая же как и apply_filters(), с той лишь разницей, что параметры в прикрепленную функцию передаются в массиве. Это позволяет передать несколько параметров и некоторые из них можно передать по ссылке.

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

Хуков нет.

Возвращает

Разное. Отфильтрованное значение, после того, как все прикрепленные к хуку функции обработают это значение.

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

$args[0] = apply_filters_ref_array( $tag, $args );
$tag(строка) (обязательный)
Название фильтра (хука).
$args(массив) (обязательный)

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

// прикрепляемая функция
add_filter('my_filter', 'my_filter_func', 10, 2 ); // 2 - получит 2 параметра
function my_filter_func( $var, $var2 ){
	// $var - 1
	// $var2 - 2

	return $var;
}

apply_filters_ref_array('my_filter', array(1,2) );

Примеры

#1 Демонстрация передачи параметров

$args = array( 'arg_1', true, 'foo', 'arg_4' );
apply_filters_ref_array( 'my_filter', $args );

Эта запись равносильна такой:

apply_filters( 'my_filter', 'arg_1', true, 'foo', 'arg_4' );

#2 Пример добавления функции к фильтру

// прикрепим функцию к фильтру
add_filter('my_filter', 'my_filter_func', 10, 2 );
function my_filter_func( $orderby, & $args ){
	// изменим параметры $args за пределами этой функции
	$args[0] = 'one';
	$args[1] = 'two';

	// изменим параметр $orderby как для обычного фильтра
	$orderby = 'DESC';
	return $orderby;
}

// Определим переменные в текущем контексте
$orderby = 'ASC';
$args = array( 1, 2 );

// вызываем фильтр, который изменить переменные текущего контекста
$orderby = apply_filters_ref_array( 'my_filter', array( $orderby, & $args ) );

// проверим как изменились данные в текущем контексте переданные в фильтр
echo $orderby; //> DESC
print_r( $args ); //> array( 'one', 'two' )

#4 Передача объекта в фильтр по ссылке

Этот пример показывает как будет использоваться apply_filters_ref_array(), когда в нее нужно передать текущий объект $this. Обратите внимание, что в прикрепляемой функции нет необходимости указывать ссылку (& – просто $class, а не & $class) для получаемого параметра, потому что объекты и их свойства в PHP всегда передается по ссылке.

class A {
	var $var = 1;

	function __construct(){
		add_filter('my_filter', array( &$this, 'my_filter_func'), 10, 2 );
	}

	function my_filter_func( $orderby, $class ){
		// в этом случае не обязательно указывать & для $class,
		// потому что объекты всегда передаются по ссылке!

		// изменим объект
		$class->var = 'one';

		// изменим параметр $orderby как для обычного фильтра
		return 'DESC';
	}

	function apply_filters_and_echo(){
		// Определим переменные в текущем контексте
		$orderby = apply_filters_ref_array('my_filter', array('ASC', & $this) );

		// используем переменные
		echo $orderby ."n"; //> 'DESC'
		echo $this->var ."n"; //> 'one'
	}
}

// вызова класса
$class = new A();
$class->apply_filters_and_echo();

/* Получим:
DESC
one
*/

Код из


wp-includes/plugin.php

WP 4.7.2

<?php
function apply_filters_ref_array($tag, $args) {
	global $wp_filter, $wp_current_filter;

	// Do 'all' actions first
	if ( isset($wp_filter['all']) ) {
		$wp_current_filter[] = $tag;
		$all_args = func_get_args();
		_wp_call_all_hook($all_args);
	}

	if ( !isset($wp_filter[$tag]) ) {
		if ( isset($wp_filter['all']) )
			array_pop($wp_current_filter);
		return $args[0];
	}

	if ( !isset($wp_filter['all']) )
		$wp_current_filter[] = $tag;

	$filtered = $wp_filter[ $tag ]->apply_filters( $args[0], $args );

	array_pop( $wp_current_filter );

	return $filtered;
}