WordPress Filter 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 filter 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 a filter hook callback function.
3. Update a filter 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 a filter callback function on an existing filter hook?
3. Which parameter affects when the filter hook callback is run?
4. Which parameter affects the number of variables passed to the hook callback?

Resources

• WordPress Hooks
• add_filter function documentation

Transcript

Hey there, and welcome to Learn WordPress.

Today we’re going to learn about a WordPress development concept called filter hooks. In this video, we will cover a brief introduction to hooks, the two types of hooks, actions and filters, what are filters and how to use them, filter priority and argument parameters, and filter 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 foundation of WordPress.

There are two types of hooks, action hooks and filter hooks. These are more commonly known as actions and filters. In this video will be focusing on filters, but check out the action hooks tutorial for more information on action hooks.

Filters allow you to modify or filter some data at a specific point, which will be used later on. In order to make use of a filter, you register a function in your code to a pre existing filter hook, which is known as a callback function. To better explain this, let’s look at a filter called the_content.

This filter is defined inside the function which is used in theme templates whenever the template needs to render any post or page content. Inside that function, we see the following code content, apply_filters. Here the apply_filters function defines the filter hook with the hook name of the_content. You’ll notice that a content variable is passed as an argument of apply_filters, and that the value of a apply_filters is assigned back to the variable. In this case, again the content variable. If you look a little higher in this function, the content variable is assigned the value of the get_the_content function, which is a WordPress core function that retrieves the value of the post_content field for the current post or page in the post table. So the apply_filters function registers the filter hook, passes the value of content at this point in the code execution to any callback functions registered on this hook and requires the updated value to be passed back.

Let’s register a callback function on this filter. To register your callback function on a filter you use the WordPress add_filter function, you will need to pass the hook name and the name of your callback function as arguments to the add_filter function. Let’s take a look at what this looks like in a theme’s functions.php file.

Start by saying add_filter, then passing the filter name and then our callback function, with a slight spelling error.

Then create the callback function which accepts the relevant arguments from the filter. You don’t have to name the arguments the same as the variable name passed from the filter, but it does make it easier if you do.

In our case, it’s just called content, then we can do something with content. And make sure that we return an updated version of content back.

Notice that you have to return the updated data. This is so that the original variable being updated from the apply_filters call gets the updated data. Oops, I left a small bug. Let’s just fix this quickly.

Let’s say you wanted to add something to the end of the content of each post. You could append it to the content variable like this.

So I’m just going to start by creating an additional_content variable. And then I’m going to update content by appending additional_content.

In this example, I’m merely adding some text in a paragraph block, which renders at the bottom of each post on the front end. Let’s take a look at what that looks like in our WordPress site.

Refresh. There we go.

It’s very important to always return something back from a filter callback. Ideally, the modified content of the variable being passed to the filter. Not returning something will cause a fatal error on your WordPress site. Now let’s talk about hook priority.

If you take a look at the documentation for add_filter, you will see two additional function parameters after the hook name and the callback function. The third parameter is the hook priority, which is an integer which defaults to 10. This means if you register a filter 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 to 10 unless you specifically want to change the order in which your callback function is run. For example, in your the_content filter example, you may want to make sure that the registered callback function is only run after any callbacks registered by WordPress core are run. Because WordPress core registers any hook callbacks with the default priority of 10, if you specify a priority of 11, like this, you can make sure your callback function is run after any core callbacks have been completed. Alternatively, if you want to make sure your callback is run before WordPress core’s you could set a lower priority, say nine. Often you might see callbacks being registered with a higher priority, either 99 or sometimes even 9999. This is because the plugin or theme developer wants to be sure that their callback is run after all other callback functions. However, one can never really know at what priority other third party plugins or themes might register their callbacks, so it’s a bit of a guess.

The fourth parameter available to the add_filter 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 another content related filter hook. In this case, get_the_excerpt. This filter is defined in the wp-include/post-template.php file on line 492. The filter is defined in the get_excerpt function, which in turn is called from the_excerpt function. This function is typically used when displaying search results where it’s useful to show the post excerpt and not the post content.

Getting back to the filter. Here, the apply_filters function is registering the filter hook with two variables that are associated with the filter, the post excerpt and the post object. When defining a filter hook using apply_filters, 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 callback function. If you look at the documentation for apply_filters, you will see the default value for the number of accepted arguments is one. Which means that if you don’t specify a value for this parameter, the first argument will be available to be passed to the callback function. In the get_excerpt filter there are two possible variables to be accepted. So 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 excerpt. Let’s see what that looks like.

The add_filter, again the filter name and our callback. Priority, and now we can define our function.

And because we haven’t specified number of accepted arguments, the post excerpt will automatically be sent. In order to accept more of the available arguments, you need to specify the number of arguments to accept. So in our case, we have two possible arguments we can accept. So if we update the number of accepted arguments to two, our function can also accept the post object.

Being able to determine which arguments you need for your callback function, and setting the number in the hook registration, is a valuable skill. For example, let’s say you just wanted to add a simple piece of text after the excerpt similar to what we did with the content. In that case, you would only need the post excerpt, so you can leave out the accepted argument setting.

So if we remove that we know we’re only receiving one argument. And then we can add something to the post excerpt. And finally, return it. Notice I’m also updating the priority to eleven. You might do this because you want to make sure the text is amended after any core filter callbacks assigned to this filter have been run. Let’s take a look at how this looks in our search results.

So I’m going to simulate a search just by passing in the search variable and give it a string. And there we go “verified by search engine”. However, what if you wanted to include something from the post, say the post title. In that case, you will update your callback to accept both arguments from the hook to get the post title from the post object.

So we update our number of arguments. Then we can add the post object from the original filter registration. And here we could do something like this, adding the post title to our additional content string. Let’s see what this looks like in our search results. Here we go and it includes the post title.

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

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