apply_filters_ref_array() │ WP 3.0.0

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

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

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

// вызовем хук
$filtered = apply_filters_ref_array( 'my_filter', [ 10, 2, 3 ] ); //> 10

// теперь, прикрепим функцию
add_filter( 'my_filter', 'my_filter_func', 10, 3 ); // 3 - получит 3 параметра
function my_filter_func( $var, $var2, $var3 ){
	return $var2 + $var3;
}

// вызовем хук еще рас, но теперь к нему прикреплена функция my_filter_func()
$filtered = apply_filters_ref_array( 'my_filter', array( 10, 2, 3 ) ); //> 5

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

Также, во втором параметре мы передаем переменную по ссылке и в прикрепленной функции my_filter_func() получаем её по ссылке. Таким образом при изменение этой переменной внутри прикрепленной функции, она также изменится и за пределами функции.

// прикрепим функцию к фильтру
add_filter( 'my_filter', 'my_filter_func', 10, 2 );

function my_filter_func( $orderby, & $link ){

	// изменим параметр $link по ссылке
	$link = 'new val';

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

Теперь попробуем вызвать фильтр разными способами:

Вызов 1 (все работает как надо)

Вызываем через apply_filters_ref_array() и указываем ссылку на второй параметр.

// Определим переменную, которую хотим передать по ссылке
$link = 'old val';

// вызываем фильтр
echo apply_filters_ref_array( 'my_filter', [ 'ASC', & $link ] ); // DESC

// проверим как изменилась переменная по ссылке
echo $link; // new val

Вызов 2 (Parse Error)

Пробуем сделать тоже самое что и выше, только через apply_filters():

$link = 'old val';

// Parse Error: syntax error, unexpected '&', expecting ')'
echo apply_filters( 'my_filter', 'ASC', & $link );

Вызов 3 (Warning)

Пробуем сделать тоже самое что и выше, через apply_filters(), только передаем переменную которая сама является ссылкой на другую переменную:

$link = 'old val';

$create_link = & $link;

echo apply_filters( 'my_filter', 'ASC', $create_link ); // DESC

// Warning: Parameter 2 to my_filter_func() expected to be a reference

echo $link; // old val

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

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

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

class A {

	var $var = 'один';

	function __construct(){

		add_filter( 'my_filter', [ $this, 'filter_func' ], 10, 2 );
	}

	function filter_func( $orderby, $class ){

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

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

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

	function apply_filters_and_echo(){

		$orderby = apply_filters( 'my_filter', 'ASC', $this );

		var_dump( $orderby );   // string(4) "DESC"
		var_dump( $this->var ); // string(3) "one"
	}

}

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

/* Получим:
string(4) "DESC"
string(3) "one"
*/