The reason of WordPress being the most popular content management system in the world is, of course, its flexibility. The beautifully simple structure of "hooks" gives WordPress this ability. Without filter hooks and action hooks, WordPress wouldn't be extendible as much and we wouldn't be able to have such a large spectrum of WordPress plugins or themes.

In this series, we're going to go through actions, one of the two kinds of WordPress hooks. Over the course of the series, we'll cover almost everything there is to know about actions:

• In the first part, which also happens to be this article, we're going to learn what WordPress actions are and how to use actions with seven core functions.
• In the next five parts, we're going to see a whopping set of examples about WordPress actions. In each part, we're going to go through 10 actions by learning what they're good for and doing one example for each action.
• In the series finale, we'll be recapping what we learned and the 50 action examples we did.

It's going to be long, incredible ride. Buckle up!

What is a WordPress Action?

In the Codex, actions are defined as follows:

Actions are triggered by specific events that take place in WordPress, such as publishing a post, changing themes, or displaying an administration screen. Action is a custom PHP function defined in your plugin (or theme) and hooked, i.e. set to respond, to some of these events.

So, in essence, actions are functions triggered by a WordPress event and run before or after the event. Actions are one of the two kinds of "hooks" in WordPress – the other one is called "filters" which we covered a while ago – check out the "Fifty Filters of WordPress" if you want to learn more about WordPress filters.

Using Actions in WordPress

Defining what actions are is the easiest thing we'll do in this series. Luckily, learning how to create and use actions is almost as easy. Let's see how we hook functions to actions, create new actions, remove existing ones and other action-related functions in the WordPress core.

Hooking a Function to an Action

Probably the easiest function among these is this one: It's used to hook our function to the action hook we're going to use:

<?php

add_action( $hook_name, $function_name, $priority, $arguments );

?>

Let's see what those parameters mean:

• $hook_name is the name of the action hook we're going to use
• $function_name is the name of our function
• $priority is an integer we specify to set how early the function's going to be run in the action hook
• $arguments is the number of arguments that our function uses and the action hook allows

Let's see a quick example:

<?php

add_action( 'add_meta_boxes', 'my_function', 10, 2 );

function my_function( $post_type, $post ) {
	// do stuff with $post_type and $post
}

?>

Almost too easy, right?

Removing Functions from an Action Hook

We have two functions to remove functions from action hooks: remove_action() and remove_all_actions(). Let's see how we use them:

<?php

// remove_action( $hook_name, $function_name, $priority );
remove_action( 'login_enqueue_scripts', 'some_function', 10 );

// remove_all_actions( $hook_name, $priority
remove_all_actions( 'wp_enqueue_scripts', 10 );

?>

The remove_action() function has three parameters: the name of the hook, the name of the function that we're going to remove from the hook, and the priority that's been set while using add_action(). The remove_all_actions() function doesn't have the $function_name parameter, since it removes all functions hooked to the action.

Creating an Action Hook

If you develop WordPress plugins or themes, its good practice to create some hooks in your code so that other developers can extend your plugin or theme. To do so, we have two functions again: do_action() and do_action_ref_array(). Let's see how the first one works:

<?php

do_action( $hook_name, $arg1, $arg2, /* ... */ $argN );

/*
 * Usage:
 * 
 * add_action( hook_name, my_function )
 * 
 * function my_function( $arg1, $arg2 ) {
 *     // do stuff with $arg1, $arg2 and so on
 * }
 * 
 */

?>

As you can see, the function virtually has an infinite number of parameters since you can define as many arguments as you need. If you need to keep your arguments in an array, though, you need to use the second function:

<?php

$args = array( $arg1, $arg2, /* ... */ $argN );

do_action_ref_array( $hook_name, $args );

/*
 * Usage:
 * 
 * add_action( hook_name, my_function )
 * 
 * function my_function( $args ) {
 *     // do stuff with $args[0], $args[1] and so on
 * }
 * 
 */

?>

Retrieving the Number of Times an Action Is Fired

If you ever need to know how many times an action is called, you can use this handy function to count action calls:

<?php

function tuts_foo() {
	$action_count = did_action( 'some_action_name' );
	if ( 1 === $action_count ) {
		// run code if 'some_action_name' has been fired only once
	}
}

?>

As you can see, the only parameter the function has is the name of the action hook.

Checking if Anything's Hooked to an Action

Imagine you're developing an extension for a popular WordPress plugin and you need to check if the user has installed the plugin or not. (After all, your plugin will not work if the other one is not installed and activated.) 

To check it, you can use the has_action() function to make sure that the popular plugin's action is available:

<?php

if( has_action( 'some_popular_plugin_action' ) {
	add_action( 'some_popular_plugin_action', 'extension_to_the_some_popular_plugin' );
} else {
	wp_die( 'Sorry to kill your website but I need "Some Popular Plugin" to work with.' );
	// CAUTION: This is a joke. Don't shut down a website because your plugin can't work with it.
}

?>

Just like the did_action() function, the has_action() function has only one parameter: the name of the action hook.

Conclusion

Now we've covered pretty much everything about creating and using actions, we can continue to a five-articles-long journey of action examples. We'll be reviewing only fifty of them but if you're curious, you can find hundreds more in the core.

I hope you'll enjoy this series as much as I did while creating the whole thing. If you think you can help me with the tutorials by suggesting more actions and asking for more examples, don't hesitate to tell me and share your thoughts by commenting below. And if you liked what you read in this series, don't forget to share the articles!

See you in the next tutorial!