do_action( string $tag,  $arg = '' )

Execute functions hooked on a specific action hook.


Description Description

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

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


Parameters Parameters

$tag

(string) (Required) The name of the action to be executed.

$arg,...

(mixed) (Optional) Additional arguments which are passed on to the functions hooked to the action. Default empty.


Top ↑

Source Source

File: wp-includes/plugin.php

function do_action( $tag, $arg = '' ) {
	global $wp_filter, $wp_actions, $wp_current_filter;

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

	// Do 'all' actions first
	if ( isset( $wp_filter['all'] ) ) {
		$wp_current_filter[] = $tag;
		$all_args            = func_get_args();
		_wp_call_all_hook( $all_args );
	}

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

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

	$args = array();
	if ( is_array( $arg ) && 1 == count( $arg ) && isset( $arg[0] ) && is_object( $arg[0] ) ) { // array(&$this)
		$args[] =& $arg[0];
	} else {
		$args[] = $arg;
	}
	for ( $a = 2, $num = func_num_args(); $a < $num; $a++ ) {
		$args[] = func_get_arg( $a );
	}

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

	array_pop( $wp_current_filter );
}

Top ↑

Changelog Changelog

Changelog
Version Description
1.2.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Codex

    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 2 content
    Contributed by Michael Nelson

    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

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