Adding Custom Hooks in WordPress: Custom Filters

In this two-part series, we're taking a look at the WordPress hook system. Specifically, we're taking a close look at both actions and filters and the role they play in WordPress development.

Though they are both defined as hooks, each plays a specific role in WordPress development. And if you're looking to become a more accomplished WordPress developer, it's important to understand not only the difference between them but also how you can implement custom hooks.

In the first post in the series, we defined what hooks were, saw how they were used elsewhere, and also reviewed actions including how to define our own. If you haven't caught the first article, I highly recommend reading it before proceeding with this tutorial.

Before getting started with hooks, I'll provide a quick refresher of what was discussed in the previous article, and then we'll move forward from there.

With said that, let's get started.

A Quick Refresh

In the previous article, we saw how hooks are an implementation of the event-driven design pattern. In particular, we defined it as the following:

• The software has certain points in which it broadcasts a message that something has happened.
• We, as developers, are able to write code that listens for this message and then respond to it with custom code.

And then throughout the content, we reviewed exactly how this pattern is implemented in WordPress. We talked about how we can take advantage of it, and then we talked about how we can implement our own action.

We recognized a subtle distinction, too:

Actions are intended to work with functionality, and filters are meant to work with data.

Whereas actions allow us to modify the way something behaves, filters are going to allow us to modify data before it's saved, retrieved, or displayed on the screen. In this tutorial, we're going to take a look at how to work with filters before writing data to the screen, such as how to lowercase the text.

Ultimately, it's about trying to have fun and see tangible results through the work we're doing while learning all about this powerful aspect of WordPress.

Before we do that, we need to make sure that we have our local development environment set up and ready to go.

Getting Started

Recall from the previous article that our local development environment should consist of the following:

• WordPress 6.0.1
• your preferred IDE
• a web server
• a copy of PHP
• a database

For many, Apache, PHP, and MySQL can be easily installed. If you're more advanced then you may be using something such as Nginx and an alternative database. If that's the case, that's fine, but for the purposes of this tutorial I'm assuming you have the former.

And if you don't have any of that set up, then no worries: We've got you covered. The linked tutorial will provide you with everything you need to get started working with WordPress on your local machine.

Once you're set up, we'll be ready to proceed.

Understanding WordPress Filters

The WordPress Code Reference provides a comprehensive set of resources for those looking to learn all about filters. As we've stated, it defines filters as the following:

Custom Filters differ from custom Actions because custom Actions allow you to add or remove code from existing Actions. Whereas custom Filters allow you to replace specific data (such as a variable) found within an existing Action.

But if you're looking for an entire list of the available filters in WordPress, then be sure to reference (and bookmark) this page in the Codex. It has roughly 20 seconds worth of filters, many of which are linked to their own page of documentation.

This means if you're curious if a specific filter exists, then you can reference this page. Similarly, you can visit that particular filter's page in order to view the argument's parameters, an example function definition, and how to work with it.

A Word About Priority and Parameters

Before we go any further, I want to make sure that we're all on the same page as to what priority and the number of arguments are referring to whenever we talk about them in the context of WordPress hooks.

Take, for example, the following line of code:

<?php<br>add_filter( 'author_edit_pre', 'filter_function_name', 10, 2 );<br>

This tells us four things:

1. the name of the filter that we're hooking into
2. the name of the function that should be called
3. the priority of when the function should be called
4. how many parameters the function should accept

Generally speaking, the first two points are quickly understood; however, the other two can often trip up new developers, but it's not a hard concept to understand.

First, think of priority as when the function is called. Remember, since a given hook can have multiple functions associated with it, priority allows you to define how soon or how late your function is called. The lower the number, the sooner it fires; the higher the number, the later it fires.

Second, the number indicates how many parameters an argument takes. If you don't specify a number, it will either accept none or whatever the default argument is. If you want to pass a different amount than what's expected, then you would specify how many parameters the argument should accept. We'll see this in more detail later in the tutorial.

Working With Filters

To begin working with filters, let's go ahead and create our own file in the root of the twentytwentytwo directory. We'll call the file the_content filter hook. Then, we will use the apply_filters

This is where we begin to take interest in str_replace() function. However, we need to change the way in which the filter is registered with WordPress, and then we need to make sure that the function registered with WordPress properly calls apply_filters<code>apply_filters.

Since we've seen how to add our own filter, specify a priority, define the number of arguments it should accept, and implement a function, I won't waste time with trivial details.

Here's the filter and it being called all on its own:

<?php<br>add_filter( 'author_edit_pre', 'filter_function_name', 10, 2 );<br>

The output with the above filter will look like the image below:

And then this is how you can call it from within the initial hook.

Calling Them All Together

Finally, it's possible to call apply_filters<code>apply_filters multiple times:

<?php<br><br>add_filter( 'tutsplus_replace_country', 'tutsplus_replace_country_callback', 10, 1 );<br>function tutsplus_replace_country_callback( $content ) {<br>    return str_replace( 'Canada', 'U.S.', $content );<br>}<br><br>add_filter( 'the_content', 'tutsplus_the_content' );<br>function tutsplus_the_content( $content ) {<br><br>    // Proceed with this function only if we are viewing a particular post.<br>    if ( is_single() && get_the_ID() == 66) {<br>		return apply_filters( 'tutsplus_replace_country', $content );<br>	} else {<br>        return $content;<br>    }<br>}<br>

Here is the final result of applying both the filters together:

Notice that this achieves the combined result of the previous cases, but it does so by condensing them into a single line of code. There are other ways that this could be written as well, but the purpose of this tutorial is to educate you on how to write your own filters and how to take advantage of apply_filters<code>apply_filters in your work.

Conclusion

This tutorial concludes our introduction to WordPress hooks. Throughout the series, we've reviewed how to take advantage of existing actions and filters, as well as how to create and implement our own.

The hook system is one of the most powerful aspects of WordPress for developers, so it's important to become familiar with it. In doing so, you're not only able to manipulate behavior and data that WordPress provides, but you're also able to define hooks that other developers can use throughout their code.

This post has been updated with contributions from Nitish Kumar. Nitish is a web developer with experience in creating eCommerce websites on various platforms. He spends his free time working on personal projects that make his everyday life easier or taking long evening walks with friends.

The above is the detailed content of Adding Custom Hooks in WordPress: Custom Filters. For more information, please follow other related articles on the PHP Chinese website!