do_action_ref_array( string $hook_name, array $args )

Calls the callback functions that have been added to an action hook, specifying arguments in an array.

Description

See also

  • do_action(): This function is identical, but the arguments passed to the functions hooked to $hook_name are supplied using an array.

Parameters

$hook_namestringrequired
The name of the action to be executed.
$argsarrayrequired
The arguments supplied to the functions hooked to $hook_name.

More Information

  • This function can be useful when your arguments are already in an array, and/or when there are many arguments to pass. Just make sure that your arguments are in the proper order!
  • Before PHP 5.4, your callback is passed a reference pointer to the array. Your callback can use this pointer to access all the array elements. Adding action and declaring a call back that hooks the above example action could look like this:

add_action('my_action', 'my_callback');
function my_callback( $args ) {
//access values with $args[0], $args[1] etc.
}

Because the array was passed by reference, any changes to the array elements are applied to the original array outside of the function’s scope.

  • Regardless of PHP version, you can specify the number of array elements when adding the action, and receive each element in a separate parameter in the callback function declaration like so:

  • add_action('my_action', 'my_callback', 10, 4 );
    function my_callback( $arg1, $arg2, $arg3, $arg4 ) {
    //access values with $args1, $args2 etc.
    }

    This method copies the array elements into the parameter variables. Any changes to the parameter variables do not affect the original array.

  • As of PHP 5.4, the array is no longer passed by reference despite the function’s name. You cannot even use the reference sign ‘&’ because call time pass by reference now throws an error. What you can do is pass the reference pointer as an array element. Doing so does require all callbacks added to the action to expect a reference pointer.

  • do_action_ref_array( 'my_action', array( &$args ) );
    
    add_action('my_action', 'my_callback');
    function my_callback( &$args ) {
    //access values with $args[0], $args[1] etc.
    }

    Because the original array was passed by reference, any changes to the array elements are applied to the original array outside of the function’s scope.

    If the array contains an object reference, the technique is as follows:

    do_action_ref_array( 'my_action', array( &$my_object ) );
    
    add_action('my_action', 'my_callback');
    function my_callback( $my_object ) {
    // $my_object->some_method()... etc.
    }

    The object’s properties can be changed. See the action ‘phpmailer_init‘ with the callback fix_phpmailer_messageid() in WordPress for an example.

    Source

    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 );
    }
    

    Changelog

    VersionDescription
    2.1.0Introduced.

    User Contributed Notes

    1. Skip to note 4 content

      Here’s a variation on the “separate parameters” example given above. It allows you to specify separate parameters -and- modify them:

      Hook:

      do_action_ref_array( 'wpdocs_my_action', array( &$arg1, &$arg2, &$arg3, &$arg4 ) );

      Callback:

      add_action( 'wpdocs_my_action', 'wpdocs_my_callback', 10, 4 );
      function wpdocs_my_callback( &$arg1, &$arg2, &$arg3, &$arg4 ) ) {
          // access and modify values with $args1, $args2 etc.
      }

    You must log in before being able to contribute a note or feedback.