Dat Tran

I'm a developer. I love to learn new things. I write about WordPress at http://binarycarpenter.com/

How Do Filters Work In WordPress

To be very honest, I've been developing for WordPress for quite some time (more than a year) but the idea of filters and actions still unclear to me. So recently, I decided to solve this problem once and for all.
In this post, I'll share with you what I found out about WordPress' filters. Hopefully, it can make this topic clearer for you.
Let's get started.

Why do you want to use add_filter and apply_filters

I'll put this short:
  • If you want to modify an existing piece of data, you'll use add_filter to add a function to modify that piece of data
  • You use apply_filters to run all functions that added using add_filter and return the data, after modified by all functions above

A quick example

A piece of code is worth a thousand lines of text so here is a quick example:
$my_name = 'Luis';

add_filter('my_name', 'uppercase_it');

function uppercase_it($name)
{
	return strtoupper($name);
}

$new_name = apply_filters('my_name', $my_name);

dump($new_name);
As you can guess, $new_name is "LUIS" and it's what we see on the screen (I'm using var_dumper library here).

Some quick note

As you can see from the example above, the add_filter accepts two parameters. The first one is a tag and the second is a function. Adding function to a filter tag is useless if you don't call apply_filters with the same tag somewhere.
When apply_filters run on a particular tag, it will call all functions that added to that tag.

Multiple add_filter

You can add as many function to a tag as you like. Let's add another function to my_name


$my_name = 'Luis';

add_filter('my_name', 'uppercase_it');

add_filter('my_name', 'add_family_name');

function uppercase_it($name)
{
	return strtoupper($name);
}

function add_family_name($name)
{
	return $name . ' Hernandez';
}


$new_name = apply_filters('my_name', $my_name);

dump($new_name);
As you can see, I added another function to the tag my_name. This function adds ' Hernandez' after the name. $new_name now would be:
As you can see, order of add_filter matters. If I swap the order of the two filters (put the filter with 'add_family_name' above of 'uppercase_it'), $new_name would be:

Multiple apply_filters

Similar to add_filter, you can call apply_filters as many time as you like. Let's look at the code below:
<?php



$my_name = 'Luis';

add_filter('my_name', 'add_family_name');

add_filter('my_name', 'uppercase_it');

function uppercase_it($name)
{
	return strtoupper($name);
}

function add_family_name($name)
{
	return $name . ' Hernandez';
}


$new_name = apply_filters('my_name', $my_name);
$new_name2 = apply_filters('my_name', $my_name);

dump($new_name);
dump($new_name2);
You can guess that I got two identical result:
Now, the place you put apply_filters matters. If I put one apply_filters after the first add_filter (but before the second add_filter) and the other apply_filters below all, the two results are different:

$my_name = 'Luis';

add_filter('my_name', 'add_family_name');

$name_1 = apply_filters('my_name', $my_name);

add_filter('my_name', 'uppercase_it');

$name_2 = apply_filters('my_name', $my_name);

dump($name_1);
dump($name_2);
However, the order depends on another thing called priority We'll discuss it later in this post.

Dig into apply_filters

Now let's take a peek inside apply_filters. It's quite a long function so I'd suggest you view the full source code here.
Let's take a look at the first line:
global $wp_filter, $wp_current_filter;
$wp_filter is an array that stores all the data about tags and their functions. Let's take a look at the tag 'my_name' by adding the following code below:
if ($tag == 'my_name')	{
    dump($wp_filter[$tag]);
}
Here is the result:
As you can see $wp_filter['my_name'] is an instance of WP_Hook. Let's ignore all other details and focus on the callback property.
You'll see that it's an associated array with the key (10) is the priority. Since I didn't specify the priority when calling add_filter, the default value is 10. WordPress use the priority to determine the order that functions are called.
If I specify the priority as below:
add_filter('my_name', 'add_family_name', 12);
add_filter('my_name', 'uppercase_it', 13);
Then, the callback array will have two key, 12 and 13:

Conclusion

Hopefully the examples in this post helped you understand filters in WordPress a bit more. If you enjoy the post, don't forget to checkout my blog here where I write about WordPress & WooCommerce tips.

Tags

Comments

More by Dat Tran

Topics of interest