do_action_ref_array() │ WP 2.1.0

Creates an action (hook) on which PHP functions can then be attached. The arguments are passed as an array.

This function is identical to do_action(). The difference is that the arguments of this hook are passed as an array. This makes it possible to pass a simple variable by reference, see example.

This function is also useful when we don't know beforehand what function will be called and how many parameters it has. Using this hook allows developers to specify the number of parameters the callback function can get. See example:

No Hooks.

Return

null. Nothing (null).

Usage

do_action_ref_array( $hook_name, $args );

$hook_name(string) (required): The name of the action to be executed.
$args(array) (required): The parameters supplied to the functions hooked to specified in $hook_name hook.

Examples

#1 The difference with do_action()

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

// this is the same as

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

do_action_ref_array( 'my_action', $args );

#2 Example of creating a hook with passing a parameter by reference {#refargpass}

You can specify a reference to an array element and specify that the callback function variables also expect a reference. So, if you change an array element in a callback function, the value of that element will also change (outside of the function scope).

// add a callback function to the hook
add_action( 'myhook', 'myhook_func' );

function myhook_func( & $num ){
	$num = 2; // Change the variable by reference
}

$num = 1;

// hook call
do_action_ref_array( 'myhook', array( & $num ) );

echo $num; //> 2

#3 An example of creating a hook with passing an object by reference.

If the array contains an object, you don't need to pass any references, the object is always passed by reference anyway:

// add a callback function to the hook
add_action( 'my_action', 'my_callback' );

function my_callback( $my_object ) {
	$my_object->prop += 2; // add 2
}

// Create an object
$my_object = new stdClass();
$my_object->prop = 1;

// launch the hook
do_action_ref_array( 'my_action', array( $my_object ) );

// see that the object has changed
var_dump( $my_object->prop ); // int(3)

Since the object is passed by reference automatically, we can use the standard do_action() function instead of do_action_ref_array() in this case:

do_action( 'my_action', $my_object );

// see that the object has changed
var_dump( $my_object->prop ); //> int(5)

#4 Passing multiple parameters {#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
)
*/

// With PHP 5.6 you can do the following:

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

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

Notes

See: 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. String[]. $wp_current_filter Stores the list of current filters with the current one last.

Changelog

Since 2.1.0

Introduced.

`do_action_ref_array() do action ref array` code ^{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 );
}