One of the best things the WordPress developers have provided us with is the use of filters. These simple yet potent little hooks allow you to adjust any plugin, theme, or WordPress behavior.

Anatomy of a filter

The WordPress function add_filter() consists of four parts, annotated by a dollar token:

add_filter( $tag, $function_to_add, $priority, $accepted_args );

• The tag, which binds your filter to the hook set by the original developer ($tag).
• The function to use, set by you, which filters the value ($function_to_add).
• The priority, which changes the order of the filters ($priority).
• And the accepted arguments, which tells how many input arguments are passed on ($accepted_args).

(Source)

How it works

To get started, a WordPress filter should always return a value. The creator of the filter may pass arguments through this filter; the first argument is the suggested return value. Moreover, the filter must be registered before the hook is fired. Below you can find a simple example, where the original developer inputs 5, but where you want to count up by 1.

// Register the filter before the hook fires.
function add_one( $decimal ) {
	return $decimal + 1;
}		
add_filter( 'some_decimal_filter', 'add_one' );

$original_decimal = 5;

// Fire the filter hook.
$filtered_decimal = apply_filters( 'some_decimal_filter', $original_decimal );

echo $original_decimal; // Output: 5
echo $filtered_decimal; // Output: 6

Add more filter arguments

More arguments can be added to a filter. For example, a user-defined option or environmental information (are we on a page or archive?). Below you can see this in action. Keep in mind that we need to tell add_filter() that there are more than one arguments forwarded.

// Register the filter before the hook fires.
function add_favorite_decimal( $decimal, $favorite_decimal ) {
	return $decimal + $favorite_decimal;	
}
// Set filter with default priority (10) and two arguments (2).
add_filter( 'some_decimal_filter', 'add_favorite_decimal', 10, 2 );

$original_decimal = 5;
$favorite_decimal = get_option( 'favorite_decimal' ); // 3

// Fire the filter hook with two arguments.
$filtered_decimal = apply_filters( 'some_decimal_filter', $original_decimal, $favorite_decimal );

echo $original_decimal; // Output: 5
echo $favorite_decimal; // Output: 3
echo $filtered_decimal; // Output: 8

Change the priority

In WordPress filters, the priority determines the order in which filters run. A filter with a lower priority value runs earlier than one with a higher priority value. The idea is that a higher priority will override the lower one.

Note that filters with the same priority run in the order they’re registered.

// Register the filter before the hook fires.
add_filter( 'some_decimal_filter', 'remove_one', -10 );
add_filter( 'some_decimal_filter', 'make_zero',    0 );
add_filter( 'some_decimal_filter', 'add_one',     10 );

$original_decimal = 5;

// Fire the filter hook.
$filtered_decimal = apply_filters( 'some_decimal_filter', $original_decimal );

function remove_one( $decimal ) {

	echo $decimal; // Output: 5

	return $decimal - 1;
}
function make_zero( $decimal ) {

	echo $decimal; // Output: 4

	return 0;
}
function add_one( $decimal ) {

	echo $decimal; // Output: 0

	return $decimal + 1;
}

echo $original_decimal; // Output: 5
echo $filtered_decimal; // Output: 1

Default Functions

WordPress also has a few great built-in functions that helps with setting a value to a filter. These are, aptly named:

• __return_true()
• __return_false()
• __return_zero()
• __return_empty_array()
• __return_null()
• __return_empty_string()

An example using default functions

add_filter( 'some_decimal_filter', '__return_zero' );
	
$original_decimal = 5;
// Fire the filter hook.
$filtered_decimal = apply_filters( 'some_decimal_filter', $original_decimal );

echo $original_decimal; // Output: 5
echo $filtered_decimal; // Output: 0

Where do I place filters?

1. Theme functions.php (not recommended)

You can place filters in your theme’s function.php file, which will always load at the right time for most filters. Be sure to create a backup.

2. Child theme functions.php (recommended)

Because the theme’s functions.php file will be overwritten when you update the theme, you shouldn’t place custom code in there. Therefore, the use of a child theme is best advised.

3. Custom plugin (recommended)

In a custom plugin, you can freely add code as you’d wish.

A great example plugin is one of the default plugins, “Hello Dolly” by Matt Mullenweg. It is actually written to be an example. Now, “Hello Dolly” uses actions instead of filters, but they’re essentially the same thing. (This is not entirely true, but that’s a lesson for another day.)

Once you activate your custom plugin, all filters within will run!

4. Custom mu-plugin (advanced)

A mu-plugin is a “Must Use” plugin. These plugins will always run and can’t be deactivated or altered through the WordPress interface.

“Must Use” plugins also run before all regular plugins, so use them if you want to change the earliest actions.

5. Code Snippets

There’s a plugin called Code Snippets that allows you to insert and activate PHP snippets on demand via a simple user interface. This may be the easiest way to get started. Still, it shouldn’t be relied upon as a permanent solution because it makes debugging more difficult for experienced developers.

Don’t rely on filters

Filters are the most important tool provided by WordPress for plugins to manipulate and implement. However, they’re developer-oriented and added for creative scenarios. Developers may only support filters for a while and remove or change filters unannounced for many structural reasons.

When you change filters within WordPress, you may break some parts of your website that rely on unfiltered behavior.

You’ll need to test and maintain filters with every update you make to your site, so updating your WordPress installation becomes a time-consuming and risky chore because of this. We only recommend using filters if there’s no better way.