Intro to WordPress Plugin Development: Using Filters

In the first part of the Intro to WordPress Plugin Development series, we covered how to organize your plugin’s files, and the importance of unique naming (folders, files, and functions).

In this part of the series, we’ll cover how to use filters.

What are WordPress filters?

According to the WordPress codex:

Filters are functions that WordPress passes data through, at certain points in execution, just before taking some action with the data (such as adding it to the database or sending it to the browser screen)…WordPress does some filtering by default, and your plugin can add its own filtering.

In more simple terms, filters will take existing data, and add to it, modify it, or remove data from it.

How to interact with WordPress filters

WordPress has four common functions that allow us to interact with filters. Note: there are other functions that you can use to interact with a filter, but these are the most commonly used.

• add_filter(): this is used when you want to register your own filter to a plugin
• remove_filter(): this is used to remove an existing registered filter
• apply_filters(): this is used to run data through a filter registered with add_filter
• has_filter(): checks to see if a filter has been registered

For example, a filter that is used every time you load a WordPress page or post is called the_content.

WordPress uses this filter so that you can hook into it to perform some action on the content of the post.

Let’s say we want to add the featured image before the content of each post on our site. Even if your site didn’t have a lot of posts to start off with, it would be a pain to remember to have to insert the featured image into the body of the post every single time you write a new post. Using this filter will make life a whole lot easier.

We can use a filter on the_content to do this for us.

<?php
add_filter( 'the_content', 'sd_featured_image_before_content' ); 
 
function sd_featured_image_before_content( $content ) { 
    if ( is_singular('post') && has_post_thumbnail()) {
        $thumbnail = get_the_post_thumbnail();
 
        $content = $thumbnail . $content; //adds the featured image (stored in the variable $thumbnail) to the variable $content
 
    }
 
    return $content; //returns the variable $content when the_content filter is finished filtering
}

With that function being run on the_content filter, all of your posts that have a featured image will have it displayed before the post content.

WordPress has a lot of other filters, and plugins will often times add their own filters.

Using Filters

One of my plugins, WP1099, is a plugin for U.S. based businesses to help automate IRS tax filing at the end of the year. I sell this with the e-commerce plugin Easy Digital Downloads. By default, Easy Digital Downloads provides a long list of countries for customers to select from on the checkout form. Since my plugin is only useful for U.S. based businesses, I wanted to remove the rest of the countries from this list. Fortunately, Easy Digital Downloads has a filter called edd_countries that lets me modify the output of the countries on the checkout page.

Here is an abbreviated version of the function Easy Digital Downloads uses to create the list of countries a customer can choose from.

<?php
function edd_get_country_list() {
	$countries = array(
		''   => '',
		'US' => 'United States',
		'CA' => 'Canada',
		'GB' => 'United Kingdom',
		'AF' => 'Afghanistan',
		//I'm intentionally removing countries from the Easy Digital Downloads function for brevity. 
		'VG' => 'Virgin Islands (British)',
		'VI' => 'Virgin Islands (USA)',
		'WF' => 'Wallis and Futuna Islands',
		'EH' => 'Western Sahara',
		'WS' => 'Western Samoa',
		'YE' => 'Yemen',
		'ZM' => 'Zambia',
		'ZW' => 'Zimbabwe'
	);
 
	return apply_filters( 'edd_countries', $countries );
}

If you notice towards the end of that function there is a line that applies a filter to the variable $countries. This allows us to “hook” into that filter to modify the list of countries.

<?php
function wp1099_restrict_US_customers( $countries ){
	$countries = array(
		'US' => 'United States'
	);
	return $countries;
}
add_filter( 'edd_countries', 'wp1099_restrict_US_customers' );

The function takes the variable $countries, which is passed to it through the apply_filters function in the Easy Digital Downloads code above. If we wanted to, we could do other things with the $countries variable, such as sorting it or merging it with another array. In this case, though, all I want to do is change its value.

Finally, we return the modified $countries variable that only has the United States listed.

Let’s create our own filter

In this example, we’re going to be creating a list of meal choices. It does just so happen to be around lunchtime while I’m writing this, so I’m choosing food as the subject 🙂

We could use anything as the content for the filter – the same concepts apply.

<?php
function sd_meal_choices(){
	$meals = array(
		'Hamburgers',
		'Hot Dogs',
		'Tacos',
		'Salad',
		'Peanut Butter &amp; Jelly Sandwich',
		'Spaghetti'
	);
 
	if ( has_filter( 'sd_meals' ) ){
		$meals = apply_filters( 'sd_meals', $meals );
	}
 
	$display = '<ul>';
 
	foreach( $meals as $meal ){
		$display .= '<li>' . $meal . '</li>';
	}
 
	$display .= '</ul>';
 
	return $display;
}

Now if I had a plugin with this function in it that someone else was using, they might want to change my list up a bit.

Because I added the apply_filters( 'sd_meals', $meals );, they can easily do so.

Let’s see how we can add a few additional meals to the list.

<?php
add_filter( 'sd_meals', 'sd_add_meal_choices' );
function sd_add_meal_choices( $meals ){
	$new_meals = array(
		'Sushi',
		'Pizza',
		'Pot roast',
		'Chicken pot pie',
		'Salmon'
	);
 
	//this combines the $meals array and the $new_meals array
	$meals = array_merge( $new_meals, $meals );
 
	return $meals;
}

This function would modify the output of the original function by adding in the new meal choices to the array. By default, these would get added to the end of the list. If you were particular about the order, you could also sort the $meals array after merging. I’m not that particular so I’m going to leave it as is for now. I just wanted to mention it as a possibility.

Hopefully, by now, you can see just how powerful filters can be. Modifying content to fit your needs, or allowing others to modify your content to fit their needs is extremely useful.

A simple line of code allows others to modify your code without having to touch the core code of your plugin.