A Quick Introduction to Using Filters

Filter hooks are one of the the more powerful WordPress features that help to provide a huge amount of flexibility when it comes to modifying WordPress, including custom themes and plugins. There could easily be hundreds of different unique tutorials on how to use filters in themes and plugins, simply because of the huge array of things you can do with them. In this quick tutorial, I’m just going to give you a simple example that demonstrates what a filter hook does.

There are four primary core functions that you will often use when working with filters:

You can think of a filter as a method for modifying data. Take, for example, the following list of fruits:

  • apples
  • oranges
  • kumkwats
  • dragon fruit
  • peaches
  • durians

This list of fruits is displayed on one of our WordPress pages with a function like this:

function pippin_show_fruits() {
	$fruits = array(
		'apples',
		'oranges',
		'kumkwats',
		'dragon fruit',
		'peaches',
		'durians'
	);
	$list = '<ul>';
 
	foreach($fruits as $fruit) :
		$list .= '<li>' . $fruit . '</li>';
	endforeach;
 
	$list .= '</ul>';
 
	return $list;
}
 
echo pippin_show_fruits();

Well what if we want to modify the list of fruits displayed via a plugin? First we need to update out display function to include a filter. We can do that like this:

function pippin_show_fruits() {
	$fruits = array(
		'apples',
		'oranges',
		'kumkwats',
		'dragon fruit',
		'peaches',
		'durians'
	);
	$list = '<ul>';
 
	if(has_filter('pippin_add_fruits')) {
		$fruits = apply_filters('pippin_add_fruits', $fruits);
	}
 
	foreach($fruits as $fruit) :
		$list .= '<li>' . $fruit . '</li>';
	endforeach;
 
	$list .= '</ul>';
 
	return $list;
}

On line 12 we do a simple check to see if our “pippin_add_fruits” filter (which we will create in a moment) exists. If it does exist, then we apply that filter to our array.

So what happens when we apply the filter to our array of fruits? Well, it could be anything. We could selectively remove fruits, we could change their names, we could add fruits, etc. In this example, I will simply add additional fruit to the list.

First, we setup our filter function like this:

function pippin_add_extra_fruits($fruits) {
	// the $fruits parameter is an array of all fruits from the pippin_show_fruits() function
 
	return $fruits;
}
add_filter('pippin_add_fruits', 'pippin_add_extra_fruits');

The array of fruits created in our pippin_show_fruits() function is passed as a parameter. Since this is an array of all the fruits, we can do whatever we want with it. At the end of the function, we have to return the $fruits array, otherwise we will end up with a blank array.

So to add additional fruits to our list, we can do this:

function pippin_add_extra_fruits($fruits) {
	// the $fruits parameter is an array of all fruits from the pippin_show_fruits() function
 
	$extra_fruits = array(
		'plums',
		'kiwis',
		'tangerines',
		'pepino melons'
	);
 
	// combine the two arrays
	$fruits = array_merge($extra_fruits, $fruits);
 
	return $fruits;
}
add_filter('pippin_add_fruits', 'pippin_add_extra_fruits');

When our pippin_display_fruits() function displays the list of fruits, we will now see this:

  • apples
  • oranges
  • kumkwats
  • dragon fruit
  • peaches
  • durians
  • plums
  • kiwis
  • tangerines
  • pepino melons

So here’s what is really happening. In the pippin_display_fruits() function we setup the original array of fruits, then, if the filter exists, we pass that array of fruits through our filter function. This is done with the apply_filters() hook. The pippin_add_extra_fruits() function then takes the $fruits array and modifies it. Once the modification is complete, the array is returned back to the pippin_display_fruits() function, which then loops through each of the items in the array and displays them.

Real World Example

Filter hooks, almost exactly like this, are what I used in my Easy Content Types and ECPT Bonus Meta Field Types plugins. The filter hooks were used to register additional meta field types via a second plugin. Inside of the functions that setup the meta fields, in Easy Content Types, is a filter that can be used by other plugins, such as the bonus meta field types plugin, to register additional meta field types.

One of the beautiful things about filters is that you can use them to provide an “interface” for other users to modify / enhance your plugins, without requiring that they modify the original plugin’s code.

26 thoughts so far

Have your say

    • Pippin

      Thanks, AJ!

  2. yellowhousedesign

    Hey Pippin – to your knowledge is there anything that like array_merge() for switch statements? Let’s say I wanted to plug-into and extend a switch statement with additional cases. Thanks!

    • Pippin

      Yeah, it’s very easy. After your switch() statement, just do something like this:

      do_action('your_action_hook_name', $var_to_switch_on);

      Then you just attach a function that takes $var_to_switch_on as a parameter to the “your_action_hook”.

  3. Tom Carney

    Hi Pippin – great job explaining filter hooks and keeping very simple. Love the site and the tutorials, keep up the excellent work!

  4. kawser ahmed

    Hi Pippin, in your this line
    “So here’s what is really happening. In the pippin_display_fruits() function we setup the original array of fruits, then, if the filter exists, we pass that array of fruits through our filter function. This is done with the apply_filters() hook. The pippin_add_extra_fruits() function then takes the $fruits array and modifies it. Once the modification is complete, the array is returned back to the pippin_display_fruits() function, which then loops through each of the items in the array and displays them.”
    Where does the function pippin_display_fruits() function comes from?

    • Pippin

      That’s a typo, it’s supposed to pippin_show_fruits()

    • kawser ahmed

      I guessed so. Thank you very much for this post. This is the only tutorial could give me the clear understanding of apply_filters(), add_filter(), has_filter() and remove_filter() functions. You saved a lot of time of mine.

    • Ken Standifer

      So in the apply_filter you reference ‘pippin_add_fruits’ but you then build a function called ‘pippin_add_extra_fruits’. Should these be the same name or am I missing something?

    • Pippin

      “pippin_add_fruits” is the name of the filter and “pippin_add_extra_fruits” is the name of the function that is tying into the filter.

  5. Luke Lee

    Many thanks. Now I have a bit understand how filter works.

  6. stann

    great job

  7. vijay khandla

    Hi Pippin – great job explaining filter hooks and keeping very simple. Love the site and the tutorials, keep up the excellent work!

  8. whizbang99

    Simply well explained – Thanks @pippin

  9. manni65929

    Nice, but I’ve been looking for a way to edit the wc_get_product_types in woocommerce so that the only option shown in “external / affiliate product”. Do you have a plugin for that, too?

  10. Julian

    Do you have the full code anywhere. Cant get it to work and am wondering if I am putting the different code blocks in the wrong places!

  11. Bobby

    great post.
    I am the beginner of wordpress. you make me understand how it work…what if the function in the plugin and you cannot change the coding in the function. How to add “apply_filter” into function?

    • Pippin

      It’s not possible to in that case. The function will have to have a filter in it before you can modify the value.

  12. Roger Correia

    So I guess the add_filter command would have to precede the creation of these functions.

    Where do you place this code to execute? Mu-plugins directory?

  13. Sergunik

    Thanks for great explanation!

  14. mccdgxch

    Thank you for your help. I now understand the apply_filters.

  16. webmatpro

    thanks you 🙂

  17. Niaz Muhammad

    Good Example

  18. Greg Jeffries

    Really cool

    Thanks for putting together this tutorial!

Comments are closed.

Leave a reply

Join the discussion