Today we’ll be talking about the filters part of the WordPress Plugin API. As we’ve gone over before, filters are used to manipulate data either before it’s sent to the database or before it’s sent to the browser.

The concept behind filters is relatively simple, during certain points before data is sent to the database or browser, WordPress checks to see if there are any hooks that want to first handle the data. If it finds a hook, it’ll pass off the data to that hook, and wait for it to be returned before sending the data on its way.

Hooking into one of these filters is fairly simple, first need to determine what we want to filter and how we want to filter it. So, for an example, say we want to replace the word foo with the word bar in the content of the post, before the post is sent to the browser. After we’ve done that, we need to find the appropriate filter for where we want to hook in our plugin. You can determine which filter you need to use from the Filter Reference in WordPress’ documentation. For this example, the filter we will be using is called the_content. You should now find the reference to this filter in WordPress’ source code (you’ll want to find some software that allows you to search through code). I found the reference to the_content in wp-includes/post-formatting.php on line 164. Let’s take a look at that line:

[code='php']$content = apply_filters('the_content', $content);[/code]

apply_filters is where WordPress sets up the hook. The first parameter is the name of the filter, and the second parameter is the data it’s passing to you. You’ll need to look above that line to determine what the content actually is that it’s passing you. Okay, so, we have now determined that the filter is only passing us 1 parameter, and that the parameter is the content of the post.

Now, we need to create a function that will filter the provided parameter and replace all instances of foo with bar. Let’s look at what that function might look like:

[code='php']function filter_foo_bar( $content ) {
$content = str_replace( 'foo', 'bar', $content );
return $content;
}[/code]

First of all, your function name must be unique. To prevent function name collisions with other plugins, it is recommended that you prepend your initials to your function name. Second, notice that the function accepts a parameter. We determined the number of parameter the hook was passing us when we looked at the filter in the context of the source code of WordPress. Within the function, we filter the content. In this example, we’re using the PHP function str_replace to replace all instances of foo with bar. Once we’re all done with the filtering, we need to return the content, so that WordPress can send it along its way.

Okay, now we need to tell WordPress where to hook this function into. We will use the WordPress function add_filter for this. We can add this either above or below our function that we created above.

[code='php']add_filter( 'the_content', 'filter_foo_bar' );[/code]

So, the first parameter of add_filter is the name of the filter. The second parameter is the name of our function that will filter the content (the function name needs to be enclosed in quotes and not have () appended to it). If your function accepts more than one parameter, you should add a third parameter to add_filter you need to first add a third parameter, the priority (just use the default of 10) and then you add a fourth parameter, which is the number of parameters your function can accept (the default is 1).

Now, I have put this all into a WordPress plugin, which you can view here.

As you can see, we have the plugin headers and we also have the license notice at the top of the plugin. If you had actually read the GNU General Public License (:P), you would know that this notice is required to be in your file (and that you’re also required to distribute a copy of the license with the download of your program. Because this is such a short plugin, I would just put it under public domain because the license is larger than the entire plugin.

Conclusion

So, we have now gone over one of the parts of the WordPress Plugin API, filters. As you may have noticed, a strong grip on the PHP development language is necessary for developing WordPress plugins, so I am writing these articles assuming that you’re already proficient in PHP.