do_action_ref_array() │ WP 2.1.0

Создает событие (хук), на который затем можно прикрепить PHP функции. Аргументы передаются в виде массива.

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

Также эта функция может быть полезна, когда мы заранее не знаем какая функция будет вызвана и сколько у нее параметров. Используя этот хук, мы дадим возможность разработчику, который его использует самому указать сколько параметров может получить функция прикрепленная к хуку. См. пример:

Хуков нет.

Возвращает

null. Ничего

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

do_action_ref_array( $tag, $arg );

$tag(строка) (обязательный): Название хука, на который будет вешаться функции через функцию add_action().
$arg(массив) (обязательный): Параметры передаваемые функции, которая будет цепляться на хук.

Примеры

#1 Разница с do_action()

do_action( 'my_action', 'arg_1', true, 'foo', 'arg_4' );

// это тоже самое что

$args = [ 'arg_1', true, 'foo', 'arg_4' ];

do_action_ref_array( 'my_action', $args );

#2 Пример создания хука с передачей параметра по ссылке:

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

// добавим коллбэк функцию к хуку
add_action( 'myhook', 'myhook_func' );

function myhook_func( & $num ){
	$num = 2; // изменяем переменную по ссылке
}

$num = 1;

// вызов хука
do_action_ref_array( 'myhook', array( & $num ) );

echo $num; //> 2

#3 Пример создания хука с передачей объекта по ссылке:

Если массив содержит объект, то никакие ссылки передавать не нужно, объект и так всегда передается по ссылке:

// добавим коллбэк функцию к хуку
add_action( 'my_action', 'my_callback' );

function my_callback( $my_object ) {
	$my_object->prop += 2; // прибавим 2
}

// Создадим объект
$my_object = new stdClass();
$my_object->prop = 1;

// запускаем хук
do_action_ref_array( 'my_action', array( $my_object ) );

// видим что объект изменился
var_dump( $my_object->prop ); // int(3)

Так как объект передается по ссылке автоматически, то в этом случае мы можем использовать стандартную функцию do_action() вместо do_action_ref_array():

do_action( 'my_action', $my_object );

// видим что объект изменился
var_dump( $my_object->prop ); //> int(5)

#4 Передача множества параметров {#multi-params}

add_action( 'my_action', 'my_callback', 10, 4 );

function my_callback( $arg1 = '', $arg2 = '', $arg3 = '', $arg4 = '' ) {

	print_r( func_get_args() );
}

$args = [ 'one', 'two', 'tree', 'four' ];

do_action( 'my_action', $args[0], $args[1] );

/*
Array
(
	[0] => one
	[1] => two
)
*/

do_action_ref_array( 'my_action', $args );

/*
Array
(
	[0] => one
	[1] => two
	[2] => tree
	[3] => four
)
*/

// c PHP 5.6 можно сделать так:

do_action( 'my_action', ...$args );

/*
Array
(
	[0] => one
	[1] => two
	[2] => tree
	[3] => four
)
*/

Заметки

Смотрите: do_action() This function is identical, but the arguments passed to the
functions hooked to (hook_name) supplied using an array.
Global. WP_Hook[]. $wp_filter Stores all of the filters and actions.
Global. int[]. $wp_actions Stores the number of times each action was triggered.
Global. Строка[]. $wp_current_filter Stores the list of current filters with the current one last.

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

С версии 2.1.0

Введена.

Код `do_action_ref_array() do action ref array` ^{WP 6.5.2}

wp-includes/plugin.php

function do_action_ref_array( $hook_name, $args ) {
	global $wp_filter, $wp_actions, $wp_current_filter;

	if ( ! isset( $wp_actions[ $hook_name ] ) ) {
		$wp_actions[ $hook_name ] = 1;
	} else {
		++$wp_actions[ $hook_name ];
	}

	// Do 'all' actions first.
	if ( isset( $wp_filter['all'] ) ) {
		$wp_current_filter[] = $hook_name;
		$all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
		_wp_call_all_hook( $all_args );
	}

	if ( ! isset( $wp_filter[ $hook_name ] ) ) {
		if ( isset( $wp_filter['all'] ) ) {
			array_pop( $wp_current_filter );
		}

		return;
	}

	if ( ! isset( $wp_filter['all'] ) ) {
		$wp_current_filter[] = $hook_name;
	}

	$wp_filter[ $hook_name ]->do_action( $args );

	array_pop( $wp_current_filter );
}