Filters Explained

Like actions, filters are another type of hook. But instead of simply executing code like with an action, they allow us to filter a piece of data. Generally speaking, when a piece of data is passed through a filter, it gives you a chance to manipulate that data, before it gets used, executed, or printed out.

Concept of Filters — Filters vs Actions

When beginning to work with PHP in your child theme, action hooks are generally fairly easy to grasp. However filters seem to be a little more difficult for people to wrap their head around, at first.

I think that is just because it requires you to have more of an understanding of basic programming fundamentals, like data types, function parameters, and what it actually means to “return” something at the end of a function. But this is all very important stuff, if you’re going to be making PHP customizations from your child theme.

An action hook allows you to execute some functionality at a certain point in the loading process of your website, and a filter allows you to do the same. However, the big difference is that a filter to takes in a piece of data, which you can alter, and then return it back. That piece of data can be many things — Anything from a giant array used for something complex to maybe just a simple string of HTML code.

So, in a nutshell, an action allows you to execute some functionality at a point in the loading process of your website, while a filter allows you to alter a piece of a data at a point in the loading process.

What a Filter Looks Like

If you browse through WordPress core, or your Theme Blvd theme, you can find the function apply_filters() used often. The first parameter passed in is the name of the filter you’d hook to, and the second parameter will be the piece of data you’ll actually be altering.

$data = apply_filters('something_cool', $data);

And if you see additional parameters passed in, these are additional variables you can optionally pass into your callback function, to aid you in altering the data.

$data = apply_filters('something_cool', $data, $foo, $bar);

And here is a common type of example you’ll see within your actual theme files. Often a function’s job will be to generate the HTML markup for some isolated element, that’ll be outputted on your website. These elements generally will have some sort of filter attached the final output, which you can use to alter it.

Theoretical Examples

All right, so you can spot a filter now. You just look for any instance of apply_filters() in your theme’s files. Now let’s create some theoretical examples to illustrate how filters work.

Example 1: The Basics

So, you’re rummaging theme files and you come across a function called in the following way.

<?php echo themeblvd_get_something_cool(); ?>

This mysterious function outputs the text “Hello World” – And so now you’re on the hunt for how to modify this outputted data. So you do a search with your text editor of the theme’s files for function themeblvd_get_something in order to find where it’s declared. You come across something like the following.

/**
 * Get something cool.
 */
function themeblvd_get_something_cool() {

	$output = 'Hello World';

	return apply_filters('themeblvd_something_cool', $output);
}

Luckily, the function has a filter applied to what it’s returning. So we can use this filter “themeblvd_something_cool” to modify it in the following way using WordPress’s add_filter() function from our child theme’s functions.php.

/**
 * My mods to getting something cool.
 */
function my_something_cool( $text ) {
	return 'My New Text';
}
add_filter('themeblvd_something_cool', 'my_something_cool');

Now, the original function themeblvd_get_something_cool() will return “My New Text” instead of “Hello World” as it originally did.

And your filter function doesn’t have to be something so simple. What if we’re fine with keeping it as “Hello World” but we want to change it to a different piece of text only if it appears on the homepage?

/**
 * My mods to getting something cool.
 */
function my_something_cool( $text ) {

	if ( is_home() ) {
		$text = 'My New Text';
	}

	return $text;
}
add_filter('themeblvd_something_cool', 'my_something_cool');

As you can see above, we’re using WordPress’s add_filter() function, in its most basic form, where we’re passing in only the two required parameters by the function – (1) the name of the filter and (2) the name of our callback function.

add_filter('themeblvd_something_cool', 'my_something_cool');

Example 2: Using Optional Variables

Where this starts to get slightly more complicated is when other variables are factored into the item, with filters applied. As an example, let’s say there’s some function that takes two numbers and adds them together to return a final value.

We catch the function running “in the wild” outputting the number 6, something like the following.

<?php echo themeblvd_get_cool_val( 3, 3 ); ?>

We then locate the source of the function, looking something as follows.

/**
 * Get some cool value, from two numbers.
 */
function themeblvd_get_cool_val( $x, $y ) {
	
	$val = $x + $y;
	
	$val = apply_filters('themeblvd_cool_val', $val, $x, $y);
	
	return $val;

}

We’re now looking at the source for this themeblvd_get_cool_val() function above, and we decide we don’t want to add the numbers together, but instead multiply the numbers. Notice above that when apply_filters() is used, the variables $x and $y are passed in.

    $val = apply_filters('themeblvd_cool_val', $val, $x, $y);

This means we can utilize them in our callback function, if we wanted to, like this.

/**
 * My cooler value, from the two numbers.
 */
function my_cool_val( $val, $x, $y ) {
	return $x * $y;
}
add_filter('themeblvd_cool_val', 'my_cool_val', 10, 3);

With our my_cool_val() function declared above, we pass in three parameters.

function my_cool_val( $val, $x, $y ) {

The first is the same as our previous basic examples, which is the value we’re actually modifying. Then, because the original call to apply_filters() incorporated variables $x and $y, we can also pass these into our filter function, as well.

However, here’s the catch on getting this to work properly that most people miss the first time around. Now, look at how we used add_filter() to actually hook our callback; we passed in four parameters.

add_filter('themeblvd_cool_val', 'my_cool_val', 10, 3);

1. The name of the filter (same as before).
2. The name of our callback function (same as before).
3. The third parameter is a bit erroneous in this case, but we need to pass it in in order to get to the fourth parameter. Basically, this third parameter is the priority in which this filter gets applied. In our case, this is our only filter being added, and so it doesn’t matter. We’ll just keep this as 10 because that’s the default value WordPress has there, anyway. IF there were other filters overriding our’s, we could increase that priority number to be larger.
4. Then this fourth parameter 3 is the the number of parameters to be passed into our callback function. By default, WordPress has this as 1 and so we need to change it to 3 in this scenario. That will accomodate the three parmaters we’re passing into our callback — (1) Value being altered, (2) first helper variable, and (3) second helper variable.

Previously, I said that we could utilize these additional parameters, if we want. The reason for that is because we do have the option to not factor in $x and $y, at all, if we don’t want to. So if this was the case, we could just do the following instead.

/**
 * My cooler value, where I don't even care about 
 * the two original numbers.
 */
function my_cool_val( $val ) {
	return 10; // Make the value 10 no matter what
}
add_filter('themeblvd_cool_val', 'my_cool_val');