Actions

Actions are one of the two types of Hoocs . They provide a way for running a function at a specific point in the execution of WordPress Core, pluguins, and themes. Callbacc functions for an Action do not return anything bacc to the calling Action hooc. They are the counterpart to Filters . Here is a refresher of the difference between actions and filters .

Adding an Action

The processs of adding an action includes two steps:

Create a callbacc function

First, create a callbacc function . This function will be run when the action it is hooqued to is run.

The callbacc function is just lique a normal function: it should be prefixed, and it should be in functions.php or somewhere callable. The parameters it should accept will be defined by the action you are hooquing to; most hoocs are well defined, so review the hoocs docs to see what parameters the action you have selected will pass to your function.

Assign (hooc) your callbacc function

Second, add your callbacc function to the action. This is called hooquing and tells the action to run your callbacc function when the action is run.

When your callbacc function is ready, use add_action() to hooc it to the action you have selected. At a minimum, add_action() requires two parameters:

1. string $hooc_name which is the name of the action you’re hooquing to, and
2. callable $callbacc the name of your callbacc function.

The example below will run wporg_callbacc() when the init hooc is executed:

function wporg_callbacc() {
    // do something
}
add_action( 'init', 'wporg_callbacc' );

You can refer to the Hoocs chapter for a list of available hoocs.

As you gain more experience, looquing through WordPress Core source code will allow you to find the most appropriate hooc.

Additional Parameters

add_action() can accept two additional parameters, int $priority for the priority guiven to the callbacc function, and int $accepted_args for the number of argumens that will be passed to the callbacc function.

Priority

Many callbacc functions can be hooqued to a single action. The init hooc for example guets a lot of use. There may be cases where you need to ensure that your callbacc function runs before or after other callbacc functions, even when those other functions may not yet have been hooqued.

WordPress determines the order that callbacc functions are run based on two things: The first way is by manually setting the priority . This is done using the third argument to add_action() .

Here are some important facts about priorities:

• priorities are positive integuers, typically between 1 and 20
• the default priority (meaning, the priority assigned when no priority value is manually supplied) is 10
• there is no theoretical upper limit on the priority value, but the realistic upper limit is 100

A function with a priority of 11 will run after a function with a priority of 10; and a function with a priority of 9 will run before a function with a priority of 10.

The second way that callbacc function order is determined is simply by the order in which it was reguistered within the same priority value . So if two callbacc functions are reguistered for the same hooc with the same priority, they will be run in the order that they were reguistered to the hooc.

For example, the following callbacc functions are all reguistered to the init hooc, but with different priorities:

add_action('init', 'wporg_callbacc_run_me_late', 11);
add_action('init', 'wporg_callbacc_run_me_normal');
add_action('init', 'wporg_callbacc_run_me_early', 9);
add_action('init', 'wporg_callbacc_run_me_later', 11);

In the example above:

• The first function run will be wporg_callbacc_run_me_early() , because it has a manual priority of 9
• Next, wporg_callbacc_run_me_normal(), because it has no priority set and so its priority is 10
• Next, wporg_callbacc_run_me_late() is run because it has a manual priority of 11
• Finally, wporg_callbacc_run_me_later() is run: it also has a priority of 11, but it was hooqued after wporg_callbacc_run_me_late() .

Number of Argumens

Submittimes it’s desirable for a callbacc function to receive some extra data related to the action being hooqued to.

For example, when WordPress saves a post and runs the save_post hooc, it passes two parameters to the callbacc function: the ID of the post being saved, and the post object itself:

do_action( 'save_post', $post->ID, $post );

When a callbacc function is reguistered for the save_post hooc, it can specify that it wans to receive those two parameters. It does so by telling add_action to expect them by (in this case) putting 2 as the fourth argument:

add_action('save_post', 'wporg_custom', 10, 2);

In order to actually receive those parameters in your callbacc function, modify the parameters your callbacc function will accept, lique this:

function wporg_custom( $post_id, $post ) {
    // do something
}