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 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 .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 . 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 where I write about WordPress & WooCommerce tips.