do_action()WP 1.2.0

Creates an event (a hook for a php function). For the function to work during the action, it should be added to this action with add_action().

See also a similar function: do_action_ref_array().

IMPORTANT: If you don't pass any parameters to the hook, the hook function will still get one parameter with the value '' (an empty string).

add_action( 'action_name', function( $first ){
	var_dump( $first );
} );

do_action( 'action_name' ); // string(0) ""

Don't pass array with single object

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.

Example:

function my_callback( $should_be_an_array ){
   print_r( $should_be_an_array );
}

add_action( 'my_action', 'my_callback' );

do_action( 'my_action', array( new stdclass() ) );

/*
stdClass Object()
*/

do_action( 'my_action', array( 'array_item_thats_not_an_object') );

/*
Array (
	[0] => array_item_thats_not_an_object
)
*/

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!

In addition to actions, WordPress also has filters - apply_filters(). They work in the same way, the only difference is that the filters pass a value to the php function and this value needs to be filtered and returned.

1 time — 0.00007 sec (very fast) | 50000 times — 0.03 sec (speed of light)

No Hooks.

Return

null. Nothing.

Usage

do_action( $hook_name, ...$arg );
$hook_name(string) (required)
The name of the action to be executed.
...$arg(mixed) (required)
Additional arguments which are passed on to the functions hooked to the action.
Default: ''

Examples

#1 Usage example

You can use this function in themes, plugins etc. when you need to inject into the code execution process. For example, we do an action (do_action) from the plugin, although this action was added in the theme.

Suppose our plugin contains such code:

// Arguments that will be passed on to the functions hooked to the action.
$a = $defined; // Some dinamic variable
$b = 'Some string';

// Do the action (activate the hook)
do_action( 'my_hook', $a, $b );

And functions.php of the theme contains such code:

function do_my_hook( $a, $b ){

	// if variable $a is equal true,
	// then, for example, delete the post with ID 10
	if( $a === true ) {
		wp_delete_post( 10 );
	}

	// A here just display the value of the second variable
	echo '<br />'.$b;
}

// add function to the hook
add_action( 'my_hook', 'do_my_hook', 10, 2 );

#2 Usage example 2

Somewhere in a (mu-)plugin, theme or the core. E.g., inside your functions.php file:

/**
 * 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
 */

/**
 * 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 who_is_hook( $a, $b ) {

	print_r( $a ); // `print_r` the array data inside the 1st argument

	echo $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( 'i_am_hook', '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.";

// Executes the action hook named 'i_am_hook'
do_action( 'i_am_hook', $a, $b );

Result:

Array (
	['eye patch'] => 'yes'
	['parrot'] => true
	['wooden leg'] => 1
)
And hook said: "I ate ice cream with Peter Pan."

Notes

  • 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 1.2.0 Introduced.
Since 5.3.0 Formalized the existing and already documented ...$arg parameter by adding it to the function signature.

Code of do_action() WP 5.9.3

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