Filter Hooks

Filter hooks are quite a bit different than the their companion action hooks. Filter hooks allow you to modify content before it is passed on to be used. Plugins, themes, and even WordPress both have and use filter hooks in a variety of ways to modify data.

Filter hooks are inserted into code to allow you to “filter” (i.e., modify) certain pieces of code by hooking a custom function in.

The most common type of data that filter hooks are applied to is a basic text string, but this is definitely not always the case. Filter hooks can be for any type of data.

An easy way to think of filter hooks is the following example. Suppose you had the text “The quick brown fox jumped over a house” and you wanted to replace “quick brown fox” with “slow green turtle.” What you’d do is “filter” the text to make the change. Obviously, this is just a basic example. You can do much more than that with filters.

What does a filter hook look like?

Generally, you can find filter hooks in your plugin, theme, or WordPress code by looking for the apply_filters() function. What this function does is “apply” any filters you might add to a certain piece of data.

Let’s take our “quick brown fox” example and show you what it’d look like if it had the apply_filters() function wrapped around it.

echo apply_filters( 'quick_brown_fox', 'The quick brown fox jumped over a house' );

What you have in the above code is two parameters for apply_filters(). The first parameter is the hook name, quick_brown_fox. The second parameter is the data that filters can be applied to.

Let’s look at a real example of a filter hook in WordPress. One of my favorite hooks in WordPress is the post_class hook, which is a filter hook on the output of classes around the post wrapper element. Here’s what it looks like in the WordPress code.

return apply_filters( 'post_class', $classes, $class, $post->ID );

Whoah! That looks quite a bit different than our first example. There’s a lot more stuff there. Don’t worry though. Filter hooks can pass you multiple parameters for use. The first two parameters are still the important ones.

The filter hook name in the preceding code is post_class. The data that you can filter is $classes, which is an array of class names added to the post class output.

Adding a filter to a hook

Filter hooks don’t do much unless an actual filter is added to them. If you want to add a filter to any filter hook, you can do so with the add_filter() function. What this function does is add your custom function (filter) to the filter hook. It is then applied when the filter hook is executed.

add_filter( $hook, $function, $priority = 10, $args = 1 );

This function takes in four parameters.

$hook

The name of the hook you want to add your filter to.

$function

Your custom function name you want to use as a filter.

$priority

What priority you want to give to your action. The lower the number, the earlier the filter is applied. The default is 10.

$args

The number of parameters you want the filter hook to pass to your function. The default is 1. Note that this should not be higher than the number of parameters the hook actually passes.

Basic filter hook usage

Let’s revisit the “quick brown fox” example. Remember what the hook looked like in the code.

echo apply_filters( 'quick_brown_fox', 'The quick brown fox jumped over a house' );

What you’re going to do is add a custom filter to this filter hook and change “quick brown fox” to “slow green turtle” using the PHP function str_replace() (replaces characters in a text string).

Your code would look like the following.

add_filter( 'quick_brown_fox', 'my_quick_brown_fox_mod' );

function my_quick_brown_fox_mod( $text ) {

	$text = str_replace( 'quick brown fox', 'slow green turtle', $text );

	return $text;
}

Advanced filter hook usage

In an earlier example, I showed you the post_class hook, which passed multiple parameters to filters. Here’s what that hook looked like in the code.

return apply_filters( 'post_class', $classes, $class, $post->ID );

Suppose you wanted to check if a post had a custom field called class, which would then be applied to the post class. You could use something like the following code block.

add_filter( 'post_class', 'my_post_class', 10, 3 );

function my_post_class( $classes, $class, $post_id ) {

	$custom_class = get_post_meta( $post_id, 'class', true );

	if ( !empty( $custom_class ) )
		$classes[] = sanitize_html_class( $custom_class );

	return $classes;
}

You can see that we were passed the filterable data, $class, and gave it back in the same exact form, which was an array. Note the 3 added as the fourth parameter for add_filter(). We needed that to make sure we got all three parameters — $classes, $class, and $post_id — to use in our filter.

More information on filter hooks

One could write an entire chapter of a book on hooks. In fact, I’ve already done that. There’s a chapter in my book, Pro WP Plugin Development, dedicated entirely to hooks.

Hooks are part of such a much larger topic than I can cover in a single tutorial. There’s really no limit on what you can do with them. I also encourage you to read more from the hooks documentation in the WordPress Codex. It has plenty of helpful topics.