add_action() │ WP 1.2.0

Hooks a function on to a specific action.

Attaches the specified PHP function to the specified hook. The attached function will be triggered at the moment of the event which is triggered by do_action().

Actions are the hooks that the WordPress core launches at specific points during execution, or when specific events occur. Plugins can specify that one or more of its PHP functions are executed at these points, using the Action API.

Actions unlike the filters (see add_filter()) need to perform some action at the specific moment. But filters transmit and receive back the data which used in code.

In short, actions are used to do something, and filters are used to change something.

Filters are the same as Actions, they work the same way and can be used as actions in some cases. For example, we can use add_filter() instead of add_action() the result will be the same. For example, we can return the received data as it is, but also at the moment perform some operation (for example, writing to the database). However, it is necessary very rarely, because almost all the places where you need to change code logic covered with special actions (thanks to WordPress developers).

Uses: add_filter()

1 time — 0.000018 sec (very fast) | 50000 times — 0.07 sec (speed of light) | PHP 7.0.8, WP 4.7

No Hooks.

Return

true. Always returns true.

Usage

add_action( $hook_name, $callback, $priority, $accepted_args );

$hook_name(string) (required): The name of the action to add the callback to.
$callback(callable) (required): The callback to be run when the action is called.
$priority(int): Used to specify the order in which the functions associated with a particular action are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.
Default: 10
$accepted_args(int): The number of arguments the function accepts.
Default: 1

Examples

#1 Basic example

Let's send email to friends whenever a new post is published:

add_action( 'publish_post', 'email_friends' );

function email_friends( $post_ID ){

   $friends = '[email protected], [email protected]';

   wp_mail( $friends, "sally's blog updated", 'I just put something on my blog: http://blog.example.com' );
}

Similarly, you can register this hook via add_filter():

add_filter( 'publish_post', 'email_friends' );

#2 Getting an argument

do_action() passes an argument to the function and it can be used. In the previous example, such argument was the $post_ID, but we didn't use it because we didn't need it. Now, an example of how to use the passed argument:

add_action( 'comment_id_not_found', 'echo_comment_id' );
function echo_comment_id( $comment_ID ){
	echo "I just received ". $comment_ID;
}

#3 Anonymous function

An anonymous function can be passed as a Colback function, for example:

add_action( 'wp_head', function(){
	echo 'something';
});

Such anonymous functions are not working in conjunction with the PHP accelerators.

Also, it is important to know that such an anonymous function in the future cannot be removed by remove_action().

#4 Adding an action from a PHP class

If you want to use a PHP class method for an action, you must specify an array instead of the function name in the second argument. The first argument of the array must be the class name (for static method) or the class instance (for public method), and the second must be the name of the class method.

The class instance always in $this variable:

// Connecting a class method outside the class
add_action( 'wp_head', array( 'MyClass', 'my_static_method' ) );

class MyClass {
	public function __construct() {
		// The connection method of a class inside a class
		add_action( 'save_post', array( $this, 'my_public_method' ) );

		add_action( 'save_post', array( __CLASS__, 'my_static_method' ) );
	}

	public function my_public_method( $post_id ) {
		// code
	}

	static function my_static_method( $post_id ) {
		// code
	}
}

Find out the number and name of arguments

To do this simply search the code base for the matching do_action() call. For example, if you are hooking into save_post, you would find it in post.php:

do_action( 'save_post', $post_ID, $post, $update );

Now, your add_action call would look like:

add_action( 'save_post', 'my_save_post', 10, 3 );

function my_save_post( $post_ID, $post, $update ){
	// function accepts 3 arguments
	// code
}

Changelog

Since 1.2.0

Introduced.

`add_action() add action` code ^{WP 6.5.2}

wp-includes/plugin.php

function add_action( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
	return add_filter( $hook_name, $callback, $priority, $accepted_args );
}