WordPress add_filter and apply_filters

I used to find the difference between add_filter and apply_filters in WordPress quite confusing. While these two functions are related they are also entirely different. I’ll explain below how their purpose and usage differs.

apply_filters

The apply_filters function “calls the callback functions that have been added to a filter hook”. If that explanation seems clear as mud, you’re not alone. So let’s break down what’s going on with this function.

The most basic syntax for apply_filters usage looks something like this:

apply_filters( 'filter_hook_name', $value_to_filter );

In the example syntax, filter_hook_name is the name of a filter hook. This could be a WordPress core hook like 'the_content', or could be a custom hook created by a plugin, theme, or by you. WordPress lists their action and filter hooks here: https://developer.wordpress.org/reference/hooks/

Our second example parameter, $value_to_filter is the value to which any filter callback functions should be applied. This value is what will be passed to any filters that are called with the same filter hook via add_filter.

The apply_filters function also allows us to use additional parameters, which may represent values we’ll use to further affect the value being filtered. These additional parameters get passed in after the filter hook and value, as we see with $arg1 and $arg2 below.

apply_filters('filter_hook_name', $value_to_filter, $arg1, $arg2)

Usage

A common way to use apply_filters is to apply this function to a value right after we’ve set the initial value:

$tagline = get_option( 'nwd_theme_tagline' );
$tagline = apply_filters( 'nwd_custom_tagline', $tagline );

You may also see a function that takes in a parameter and returns that parameter after making it filterable with apply_filters:

function maybe_modify_value( $tagline ) {
  return apply_filters( 'nwd_custom_tagline', $tagline );
}

add_filter

The add_filter function “adds a callback function to a filter hook”, such as the filter_hook_name from the apply_filters example above:

function filter_callback( $value_to_filter ) {
    // Maybe modify $example in some way.
    return $value_to_filter;
}
add_filter( 'filter_hook_name', 'filter_callback' );

In the example above, add_filter('filter_hook_name', 'filter_callback') says “filter the value provided by the ‘filter_hook_name’ hook according to the logic of the ‘filter_callback’ function”. In other words, “take the filter_callback function and apply it wherever filter_hook_name is applied”. The filter_callback function can have any name, but the function name must exactly match the second parameter of the add_filter call.

The filter_callback function takes in the parameters/values required by the corresponding apply_filters function. At a minimum this includes the value to be filtered, which can be called anything but in our examples is $value_to_filter. The filter callback function will typically perform some kind of modifications to the value it receives and will then return a modified value. However, your filter function is not required to return a version of the value it receives, and in fact can return just about anything you’d like. For example, if I wanted to filter the built-in WordPress admin footer text, I could write something like this:

function nwd_footer_text( $footer_text ) {
    return '<span id="footer-thankyou">' . 'This site was created by a nice guy named Ryan.' . '</span>';
}
add_filter( 'admin_footer_text', 'nwd_footer_text' );

The above code completely ignores the $footer_text value it receives, instead returning custom text that changes the admin footer text from this:

to this:

Summary

The apply_filters function is used to make a particular value filterable. We use it to give others the opportunity for modification. The add_filter function is used to actually execute some kind of filtering on a value. We use this to modify the returned value of a given filter hook.

This article covers the basics of WordPress filters, but doesn’t currently dive into topics like filter priority or how to use additional arguments. If you’re looking for further explanation on WordPress filters I’d suggest checking out this talk given by my colleague Sal Ferrarello at a WordCamp conference a few years ago.