do_action( string $hook_name, mixed $arg )

Calls the callback functions that have been added to an action hook.

Description

This function invokes all functions attached to action hook $hook_name.
It is possible to create new action hooks by simply calling this function, specifying the name of the new hook using the $hook_name parameter.

You can pass extra arguments to the hooks, much like you can with apply_filters().

Example usage:

// The action callback function.
function example_callback( $arg1, $arg2 ) {
    // (maybe) do something with the args.
}
add_action( 'example_action', 'example_callback', 10, 2 );

/*
 * Trigger the actions by calling the 'example_callback()' function
 * that's hooked onto `example_action` above.
 *
 * - 'example_action' is the action hook.
 * - $arg1 and $arg2 are the additional arguments passed to the callback.
do_action( 'example_action', $arg1, $arg2 );

Parameters

$hook_namestringrequired
The name of the action to be executed.
$argmixedoptional
Additional arguments which are passed on to the functions hooked to the action. Default empty.

Source

function do_action( $hook_name, ...$arg ) {
	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;
	}

	if ( empty( $arg ) ) {
		$arg[] = '';
	} elseif ( is_array( $arg[0] ) && 1 === count( $arg[0] ) && isset( $arg[0][0] ) && is_object( $arg[0][0] ) ) {
		// Backward compatibility for PHP4-style passing of `array( &$this )` as action `$arg`.
		$arg[0] = $arg[0][0];
	}

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

	array_pop( $wp_current_filter );
}

Changelog

VersionDescription
5.3.0Formalized the existing and already documented ...$arg parameter by adding it to the function signature.
1.2.0Introduced.

User Contributed Notes

  1. Skip to note 4 content

    Example

    # ======= Somewhere in a (mu-)plugin, theme or the core ======= #
    
    /**
     * You can have as many arguments as you want,
     * but your callback function and the add_action call need to agree in number of arguments.
     * Note: `add_action` above has 2 and 'i_am_hook' accepts 2. 
     * You will find action hooks like these in a lot of themes & plugins and in many place @core
     * @see: https://codex.wordpress.org/Plugin_API/Action_Reference
     */
    
    # ======= e.g., inside your functions.php file ======= #
    
    /**
     * Define callback function
     * Inside this function you can do whatever you can imagine
     * with the variables that are loaded in the do_action() call above.
     */
    function wpdocs_who_is_hook( $a, $b ) {
    	echo '<code>';
    		print_r( $a ); // `print_r` the array data inside the 1st argument
    	echo '</code>';
    
    	echo '<br />'.$b; // echo linebreak and value of 2nd argument
    }
    
    // then add it to the action hook, matching the defined number (2) of arguments in do_action
    // see [https://codex.wordpress.org/Function_Reference/add_action] in the Codex 
    
    // add_action( $tag, $function_to_add, $priority, $accepted_args );
    add_action( 'wpdocs_i_am_hook', 'wpdocs_who_is_hook', 10, 2 );
    
    // Define the arguments for the action hook
    $a = array(
    	'eye patch'  => 'yes',
    	'parrot'     => true,
    	'wooden leg' => 1
    );
    $b = __( 'And Hook said: "I ate ice cream with Peter Pan."', 'textdomain' ); 
    
    // Executes the action hook named 'i_am_hook'
    do_action( 'wpdocs_i_am_hook', $a, $b );

    Result:

    Array ( 
    	['eye patch'] =&gt; 'yes'
    	['parrot'] =&gt; true
    	['wooden leg'] =&gt; 1
    )
    And hook said: "I ate ice cream with Peter Pan."
  2. Skip to note 5 content

    BIG GOTCHA:

    When calling do_action, if the $arg you pass in is an array with a single object, it will instead pass that obejct in and NOT an array. It doesn’t do the same switcheroo, however, if the array’s single item is anything other than an array

    E.g.,

    function my_callback( $should_be_an_array ){
       var_dump($should_be_an_array);
    }
    add_action( 'my_action', 'my_callback' );
    do_action( 'my_action', array(new stdclass()) );
    do_action( 'my_action', array( 'array_item_thats_not_an_object') );

    echoes out

    object(stdClass)[420]
    array (size=1)
      0 => string 'array_item_thats_not_an_object' (length=30)

    notice that the first time we passed in an array with an stdclass in it, but the callback function only received the stdclass, NOT an array

  3. Skip to note 6 content

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