A Guide to the Actions API

14 Comments

WordPress theme frameworks have been all the rave nowadays, and rightly so. Everybody’s either using one or rolling their own flavor. Theme frameworks introduce several new concepts to theme authoring that till now, only plugin developers have been taking advantage of. In this article, I’m going to introduce you to the actions API, and break it down so you can understand how it all works.

If you don’t already know about action hooks, they’re simple little functions that act as a placeholder to allow other functions to “hook” into that particular spot where the placeholder function was called at. Here’s an example to demonstrate that:

wp_head() an action hook which is located in your theme’s header.php is a prime example of how action hooks work. wp_head is located in your theme’s header.php. Let’s take a peak at the source:

/**
 * Fire the wp_head action
 *
 * @since 1.2.0
 * @uses do_action() Calls 'wp_head' hook.
 */
function wp_head() {
	do_action('wp_head');
}

As you’ll notice, there’s nothing actually in wp_head that prints out any scripts or meta tags. wp_head simply calls a do_action function with the first parameter being wp_head. And that’s where the magic lies: do_action();

In order to create an action hook, you simply need to create a placeholder function that calls do_action(); with the first parameter being the name of the desired hook. Typically, you’d want the name to be exactly what the function name is, but it can be anything you’d like; as long as the name isn’t already in use.

Now here’s how the magic works: Once you call the do_action('wp_head'); with the first parameter being the name of the desired hook, WordPress registers this call into the system. With the hook now registered into the system, we can now call the add_action(); function allowing us to hook into wp_head.

Viewing the source of default-filters.php where WordPress hooks into the wp_head action hook reveals this:

add_action('wp_head', 'wp_enqueue_scripts', 1);
add_action('wp_head', 'feed_links_extra', 3);
add_action('wp_head', 'rsd_link');
add_action('wp_head', 'wlwmanifest_link');
add_action('wp_head', 'index_rel_link');
add_action('wp_head', 'parent_post_rel_link', 10, 0);
add_action('wp_head', 'start_post_rel_link', 10, 0);
add_action('wp_head', 'adjacent_posts_rel_link', 10, 0);
add_action('wp_head', 'locale_stylesheet');
add_action('wp_head', 'noindex', 1);
add_action('wp_head', 'wp_print_styles', 8);
add_action('wp_head', 'wp_print_head_scripts', 9);
add_action('wp_head', 'wp_generator');

More than a dozen functions get hooked into wp_head by default. You’ll notice that the first parameter is wp_head, with the second parameter being a PHP function. What add_action does, is register those PHP functions to the wp_head action hook. So whenever a do_action('wp_head'); is called, WordPress checks to see if any PHP functions are registered to wp_head, and if so, execute them. And that’s how the WordPress actions API works.

Now why go through all that trouble when WordPress could have easily included all these functions into the actual theme itself? Well for one, the actions API makes your theme future proof. If you noticed right above the wp_head function, there was a comment stating that it was there since WordPress 1.2.0. That’s a pretty long time, and I can assure you that all those PHP functions registered to the wp_head hook weren’t there back in those days. Using the actions API, WordPress was able to use one placeholder function and hook in functionality later down the line when needed, like feed_links_extra, which was introduced in WordPress 2.8.

Using the actions API, you can also remove PHP functions registered to a particular hook using remove_action();

remove_action( 'wp_head', 'wp_generator' );

The first parameter indicates which hook we’re targeting, and the second is the actual PHP function we’d like to remove. This function is useful if your using a theme framework and would like to remove some of their default behavior.

So to recap, the actions API allows you to create placeholder functions in your template files, allowing other functions to hook into that particular spot just by registering them using the add_action call. To read more on this topic, here are a few links that also explains the matter:

The actions API is exactly how plugins are able to add features and functionality to WordPress as those little do_action() calls are made all throughout the WordPress core. Nowadays, themes are starting to get more advanced, so they started making use of the actions API to allow more flexibility and future proof. In the next article, I’ll demonstrate some creative uses for action hooks that you can use in your themes.