WordPress Action Hooks

The WordPress Hooks system is what makes WordPress so extendable, and allows you to build anything on the foundation of WordPress, from a blog to an online eCommerce platform.

In this lesson, you will learn about action hooks, how they work, how to choose the right hook, and how to use them in your code.

Learning outcomes

1. Understand the difference between action hooks and filter hooks.
2. Register an action hook callback function.
3. Update an action hook callback priority.
4. Work with hook callback accepted arguments.

Comprehension questions

1. What is the difference between an action hook and a filter hook?
2. What function is used to register an action callback function on an existing action hook?
3. Which parameter affects when the action hook callback is run?
4. Which parameter affects the number of variables passed to the hook callback?

Resources

• WordPress Hooks
• add_action function

Transcript

Hey there, and welcome to Learn WordPress.

Today we’re going to learn about a WordPress development concept called Action hooks.

In this video, we will cover a brief introduction to hooks, the two types of hooks: actions and filters, what actions are and how to use them, action hook priority and argument parameters, and action hook order.

Hooks allow your theme or plugin code to interact with or modify the execution of a WordPress request at specific predefined spots. Hooks are what Make WordPress so extendable and allow you to build anything on the foundation of WordPress, from a blog to an online e-commerce platform.

There are two types of hooks, action hooks, and filter hooks. These are more commonly known as actions and filters. In this video, we’ll focus on actions but check out the filters video for more information on filter hooks.

As the name states, actions allow you to perform some action at a specific point. To better explain this, let’s look at an example.

One common activity you will need to accomplish if you develop WordPress themes is deciding which post formats to support and then enabling support for them in your theme. To do this, the documentation indicates that you need to use the add_theme_support function and recommends that this be registered via the after_setup_theme action hook. Let’s go to the point in the WordPress code where this hook is first defined, which is currently on line 576 of the wp-settings.php file.

Here, the do_action function defines the action hook with the hook name after_setup_theme. We can also read more about this hook in the documentation.

Here we see that this hook is fired during each page load after the theme is initialized and is used to perform basic setup, registration, and initialization actions for a theme. In order to make use of an action, you register a function in your code to a pre-existing action hook, which is known as a callback function. To register your callback function on an action, you use the WordPress add_action function. You will need to pass the hook name and the name of your callback function as arguments to the add_action function. Let’s take a look at what this looks like in your themes functions.php file.

First, we use add_action, and we pass in the action hook name. Then we define our callback function. Next, create the callback function and add support for your chosen post formats. In this case, I’ll just copy the post formats from the documentation. Function, learn_setup_theme, and let’s pop over to the documentation, and grab post formats.

You can name the callback function anything you want, but it’s always a good idea to create it with a unique prefix. In this example, I’m using wp_learn. If you create a post now in your WordPress dashboard, you’ll see the post format select box appear in the Block Editor. And you can select the required post format. You can see the two post formats you enabled in your callback function: aside and gallery.

As you can see from registering an action, you use actions to perform something either enabling some already existing feature or adding something to the code execution.

Now let’s talk about hook priority. If you take a look at the documentation for add_action, you will see two additional function parameters after the hook name and callback function. The third parameter is the hook priority, which is an integer which defaults to 10. This means if you register an action in your code without specifying a priority, it will be registered with a priority of 10.

Hook priority allows you to determine the order in which your hook callback is run relative to any other hook callbacks that may be registered on the given hook, either by WordPress Core, or other themes and plugins. Hooks run in numerical order of priority starting at one. It’s usually safe to leave the priority to default of 10, unless you want specifically to change the order in which your callback function is run.

For example, in our after_setup_theme action example, you may want to make sure that the registered callback function is only run after any callbacks registered by WordPress Core run. Because WordPress Core registers any hook callbacks with a default priority of 10. If you specify a priority of 11 you can make sure your callback function is run after any core callback functions have been completed.

Alternatively, if you want to make sure the callback is run before WordPress core’s, you could set a lower priority, say nine. Often you might see callbacks being registered with a high priority like 99, or 9999. This is because the plugin or theme developer wants to be sure that this callback is run after all other callback functions. However, one can never know for sure at what priority other third-party plugins or themes might register their callbacks.

The fourth parameter in the add_action function is the number of accepted arguments the callback function can accept.

In order to better understand how this works, let’s take a look at the save_post action hook. This hook is defined in the wp-includes-post file inside of the wp_insert_post function, which is an admin function that either adds or updates a WordPress post or page. Right at the bottom of this function, we see the following piece of code. Here, the do_action function is registering the action hook with three variables that are associated with the action, the post id, the post object, and the update boolean variable.

When defining an action hook using do_action, any number of possible arguments can be added. However, the number passed to the accepted arguments parameter determines how many of them are passed to the hook callback function. If you take a look at the documentation for add_action, you will see that the default value for the number of accepted arguments is one, which means you don’t have to specify a value for this parameter. The first argument will be available passed to the callback function. In the save_post action, there are three possible variables to be accepted. If you register the callback without setting the number of arguments, only the first will be available to the callback function. In this case, the post ID. Let’s take a look at what that might look like.

So here I haven’t specified the number of accepted arguments. So the first one will always be passed. In order to accept more of the available arguments, you need to specify the number of arguments to accept.

Then you can use those arguments in your callback function.

To make life easier, I’ll just copy them over from the definition.

Being able to determine which arguments you need for your callback function, and then setting the number in the hook registration is a valuable skill. For example, let’s say you wanted to save the date a post was saved as a piece of metadata on the post using the update_post_meta function you might only need the post ID.

And then our update_post_meta function could look something like this.

However, what if you wanted to do this when the post is updated? In this case, the hook has the update variable, which if we look at the wp_insert_post code is set to true if the post is being updated. So you would need to update your callback to accept all three arguments from the hook and use the update variable in your code. Okay, so I’m going to update the number of arguments And then I’m just going to grab the variables from the action registration. And then I can use the update variable. And this way, if update is true, only then will the post meta be updated.

You will notice that I’m using the same variable names for the arguments being passed to the callback, in this case, post id, post, and update. This is not a requirement, and you can call them anything you want when you register your callback function. But it does make it easier to remember what each variable is if you name them the same.

Depending on your specific requirements, you may first need to determine which action is the correct one to use. Fortunately, the WordPress Codex has an action reference, which is a list of action hooks available in WordPress and the order that they are run during different requests on a WordPress site.

And that wraps up this tutorial on WordPress action hooks. See you next time.