Hooks — The Ultimate Guide

Hooks are the bread and butter behind each WordPress website. A hook is an execution point where WordPress checks to see if there are any callbacks to run. There are two types of hooks: an action, and a filter.

Use Cases

There are many use cases for hooks. Hooks are convenient because you don’t need class references to make method calls to modify the behavior in both WordPress Core or other plugins (assuming plugin authors add hooks). Two plugins don’t even need to know that the other exists to extend the other. They can be globally referenced meaning a theme can add a hook called by a plugin and vice versa. They are incredibly powerful and used everywhere within WordPress and it’s vast collection of plugins and themes.

Adding Callbacks for Hooks

Here is an example of how one may add a callback for an action (if the callback is a function):

add_action( 'publish_post', 'mp_publish_post' );
Code language: PHP (php)

Here’s an example of how one might add a callback referencing a method within another method of the same class:

And here’s an example of how may add a callback for a filter (if the callback is a function):

add_action( 'publish_post', 'mp_publish_post' );
Code language: PHP (php)

add_filter( 'the_content', 'mp_append_banner' );
Code language: JavaScript (javascript)

One might add a callback referencing another method within the same class:

add_action( 'publish_post', array( $this, 'publish_post' ) );
Code language: PHP (php)

add_filter( 'the_content', array( $this, 'append_banner' ) );
Code language: PHP (php)

One can reference a static method inside the same class using the following:

add_action( 'publish_post', array( __CLASS__, 'publish_post' ) );
Code language: PHP (php)

add_filter( 'the_content', array( __CLASS__, 'append_banner' ) );
Code language: PHP (php)

One can also reference a static method of a different class using the following:

add_action( 'publish_post', array( 'Another_Class', 'publish_post' ) );
Code language: PHP (php)

add_filter( 'the_content', array( 'Another_Class', 'append_banner' ) );
Code language: PHP (php)

Actions

Action callbacks are ran and do not return anything. They are often used for processing data or rendering some HTML.

Here’s an example that adds a piece of meta data to a post when it’s published:

add_action( 'publish_post', 'set_some_meta', 10, 1 );

function set_some_meta( $post_id ) {
    update_post_meta( $post->ID, 'say', 'Hello world!' );
}
Code language: PHP (php)

But what triggers the publish_post action?

WordPress calls the following function when a post is published:

do_action( "publish_post", $post->ID, $post, $old_status );
Code language: PHP (php)

As you can see the second argument given is the post ID, which was able to be retrieved in the example callback above.

If you want to access more than the first parameter in a callback, you need to change the fourth argument of add_action to 2 or 3 (in the case of the “publish_post” action). This will allow you to access $post and $old_status respectively, in the callback.

Filters

Filter callbacks are ran and modify a value passed as an argument, then return the updated value.

For example, let’s update the title of a WordPress post when you visit it:

add_filter( 'the_title', 'change_the_title', 10, 1 );

function change_the_title( $title ) {
    $title = 'Check this out - ' . $title;

    return $title;
}
Code language: PHP (php)

When WordPress is about the display the title of a post, it calls the apply_filters function with the following call:

apply_filters( 'the_title', $post_title, $post_id )
Code language: PHP (php)

Since I was only interested in accessing the existing post title ($post_title) and not $post_id, I left the fourth argument of the example add_filter call as 1, which just sends you the second argument in the apply_filters call. The 1 can be changed to 2 if $post_id needs to be accessed as well.

Priorities

Calls to both add_action and add_filter can have a priority specified. The higher priority of a callback, the sooner the callback will be executed compared to another callback (if there is one) of a lower priority. By default actions and filters have a priority of 10. As an example, an action with with a priority of 15 will be ran before an action of the same name with a priority of 10 (the default).

There are cases in which it may be useful to run an action or filter with the absolute lowest priority (to get the most-final value possible, you could say). In which, you can set the priority to 0.

In Conclusion

Hooks may seem a little confusing at first (they definitely were to me when I started extending WordPress), but you will get the hang of them fast. If you’re building a plugin or theme, it’s good practice to implement lots of hooks throughout your code so others can extend it. There’s nothing more frustrating than wanting to tweak the behavior or someone’s plugin, thinking there should be an obvious hook for it when the plugin developer never added one. That use case alone is reason why hooks are so useful when developing on WordPress.