Action Hooks

Action hooks are hooks that are executed at a certain point in a page load or when a specific event is triggered in WordPress, themes, and plugins. They allow you to “hook” custom code into your site when the hook is fired. There are potentially 100s or 1,000s of action hooks fired on each page load of your WordPress site. Some hooks are more common than others, but they all allow you to add a custom function (action) on the hook.

Action hooks are probably the most-used types of hooks by theme users because they generally just want to add some content in. This tutorial will walk you through the basics of action hooks.

Generally, when people talk about “hooks,” what they are really talking about are “action hooks.” However, action hooks should not be confused with filter hooks, which is the other type of hook available.

What does an action hook look like?

You can usually find an action hook by searching for the function do_action() in various files. The following line of code is an example of a WordPress action hook called wp_footer, which themes should call in their footer template.

do_action( 'wp_footer' );

That’s what hooks generally look like. There are other cases, but this tutorial is just covering the basics.

Some action hooks also pass parameters. An example in WordPress is the save_post hook. It passes two parameters: $post_id and $post. It looks like the following line of code.

do_action( 'save_post', $post_id, $post );

The reason some action hooks pass parameters is to give you additional information you might need. Usually, this is contextual info that will change depending on the situation. For example, the save_post hook will pass specific information about the current post being saved with its parameters.

Adding an action to a hook

You add custom functions (actions) to action hooks using the add_action() function.

add_action( $hook, $function, $priority = 10, $args = 1 );

This function takes in four parameters.

$hook: The name of the hook you want to add your function to.
$function: Your custom function name you want to execute on the hook.
$priority: What priority you want to give to your action. The lower the number, the earlier the action is executed. The default is 10.
$args: The number of parameters you want the action hook to pass to your function. The default is 1. Note that this should not be higher than the number of parameters the hook actually passes unless you leave it at the default.

Basic action hook usage

Let’s suppose you wanted to execute custom PHP code on the wp_footer hook. The following PHP code would show a copyright message in your footer.

add_action( 'wp_footer', 'my_footer_copyright' );

function my_footer_copyright() {

	echo '<p class="copyright">&copy; Copyright Theme Hybrid. All rights reserved.</p>';
}

That’s just a pretty basic HTML output, which is generally what theme users need to do with action hooks.

Advanced action hook usage

You can execute pretty much any PHP code though. Remember the save_post hook from earlier? Let’s try an advanced example using the parameters the hook passes.

Let’s suppose you want to save some post metadata when posts by the author with the ID of 100 are saved.

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

function my_save_post_meta( $post_id, $post ) {

	if ( 100 === absint( $post['post_author'] ) )
		update_post_meta( $post_id, 'example_meta', 'Justin writes awesome posts' );
}

This isn’t a particularly useful piece of code. The point is to just show you how multiple parameters are passed. Note that we added a 2 for the $args parameter in add_action(). This is so we could grab both the $post_id and $post parameters.

More information about action hooks

There’s no way I could cover action hooks in complete detail in a single tutorial. The basics are all most people need. If you want to know more, you’ll have to put in some work and break WordPress a few times.

The best place to start learning more is the documentation on hooks in the WordPress Codex.

A little shameless self-promotion: Hooks are such a large topic that there’s an entire chapter dedicated to them in my book, Pro WP Plugin Development.