WordPress Actions and Filters: What’s the Difference?

Action and filter hooks are a fundamental part of the various WordPress APIs. Without them you’re limited as to what you can do in your themes and (especially) your plugins.

But sometimes it can be easy to confuse the two, especially in the cases when WordPress has both an action hook and a filter hook with the same name.

In this article I’ll define action and filter hooks and describe the difference between them, and I’ll demonstrate how to use them in your themes and plugins. I’ll also give some examples of when you might use each.

When you’re adding action and filter hooks to your code (or you’re hooking functions to them), it helps to understand how actions and filters are called by WordPress and what happens in what order. I won’t cover that in detail here as we have another tutorial that does that job.

Definitions and Differences

Let’s start with some definitions. I’ll define action and filter hooks and functions too, so you can see the difference between them all.

Functions

Functions are the first thing most people work with when they’re learning WordPress development; if you’ve added code to your theme’s functions.php file, then you’ll have written a function.

Functions specify how something will happen. You code a function to query data, to output content, or to perform many other tasks. You can call (execute) functions directly in your theme’s template files, or you can hook them to action or filter hooks. Functions can also include template tags such as conditional tags, to specify when the function should apply.

I’ll show you the different ways to execute functions later in this article.

Action Hooks

Action hooks (or actions) are triggered when something takes place, such as loading a page, a user logging in, or a custom action that you define in your theme or plugin.

You can add your own action hooks using the do_action() function, which I’ll demonstrate shortly. Any functions you hook to that action will then run at that point in the code.

Filter Hooks

Filter hooks, or filters, control how something happens or change something that’s already being output. You could use a filter to output metadata in a specific format, to override text output by your plugin, or to prevent something from being displayed at all.

You add filters in your code using the apply_filters() function, which I’ll demonstrate shortly. As the word ‘apply’ indicates, you apply filters to existing code, whereas an action you create using do_action() is empty until you hook functions to it.

Using Functions, Actions, and Filters

Let’s take a look at some examples demonstrating how you use each of functions, actions, and filters. First, we’ll look at using functions directly in your code without attaching them to a hook.

Calling Functions Directly

Here’s an example of a function that’s called directly in a template file. In my client sites I add a colophon in the footer, which includes copyright information. Here’s the function:

if ( ! function_exists( 'compass_colophon' ) ) {
function compass_colophon() { ?>
    <section class="colophon" role="contentinfo">
		<small class="copyright left">
			<?php echo compass_copyright(); ?>
			<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
			<?php bloginfo( 'name' ); ?>
			</a>
		</small><!-- #copyright -->

		<small class="credits right">
				Powered by <a href="https://wordpress.org/">WordPress</a> and designed by <a href="https://compass-design.co.uk">Compass Design</a>.
			</a>
		</small><!-- #credits -->
	</section><!--#colophon-->
	<?php }
}

This function is pluggable as I use it in a parent theme; if I then create a new function with the same name in my child theme, that will override this function. Note that the function includes another function, compass_colophon(), calling it directly in the code.

This function is in the functions.php file of my parent theme. I can call it directly in the footer.php file of my theme, like so:

compass_colophon();

This outputs the code in the function at the point in my theme where I call it. You can also pass parameters to your functions, which are then used inside the function.

As I’ll demonstrate shortly, this function could also be hooked to an action or a filter.

Hooking Functions to Actions

Rather than calling that colophon function directly, I’ll have more flexibility if I attach it to a hook.

Creating Action Hooks

Instead of calling the compass_colophon() function in my footer file, I can add an action hook at that point in the footer.php file, by adding this:

do_action( 'compass_in_footer' );

The do_action() function has one mandatory parameter, which is the name of the action. You can also optionally add arguments to it.

Hooking Functions to Actions

So now instead of calling my colophon function, I need to hook it to my new action hook. In my functions.php file, I add this with my function:

add_action( 'compass_in_footer', 'compass_colophon' );

This hooks my function to the compass_in_footer action, which means that the code inside my function will run at the point in the code where the action has been placed. The first parameter is the name of the action hook, and the second is the name of my function.

An advantage of doing it this way is that you can hook more than one function to the same action, and you can set the priority so they fire in the order you want them to.

So let’s say I have another function I want to hook to my compass_in_footer hook, called compass_smallprint(), which contains some more small print:

if ( ! function_exists( compass_smallprint() ) ) {
    function compass_smallprint() {
		// contents of function here
	}
}
add_action( 'compass_in_footer', 'compass_smallprint', 20 );

You can see here that I’ve added a third parameter to my add_action() function, which is the priority. The default priority is 10, which will be applied if you leave this blank. So because I haven’t set a priority for my compass_colophon() function, setting 20 for the compass_smallprint() function will make that function run after the compass_colophon() function.

Unhooking Functions From Actions

Sometimes you want to stop a function from running, one way to do that is to create a dummy version of the function that does nothing if it is pluggable. Simply put, pluggable functions allow you to override some behavior depending on the order of execution of code. You might also want to learn the basics of pluggable functions and their usage to catch up if you haven’t heard about them.

Another way to achieve this is by using actions hooks. If the function has been hooked to an action hook, then you can do this using the remove_action() function. So if I want to prevent my compass_smallprint() function from running, I unhook it from the compass_in_footer action like so:

remove_action( 'compass_in_footer', 'compass_smallprint', 20 );

The remove_action() function has three parameters: the name of the action hook, the name of the function, and the priority with which the function was originally hooked to the action. You must include the priority for this to work.

You can also unhook all of the functions from an action if you want to prevent them all from executing. Be careful when doing this, as there may be functions you’re not aware of hooked to your action.

To do this, use the remove_all_actions() function:

remove_all_actions( 'compass_in_footer' );

Adding a priority number as the second parameter only removes the functions which are hooked to that action hook with the priority you’ve specified, which gives you more control.

Hooking Functions to Filters

You also have the option of hooking your functions to filter hooks. You do this when you want to alter or override some existing code. When you create the filter hook (using the apply_filters() function), you wrap that around code in your theme or plugin, which is then altered by any filters attached to the hook.

This can be useful if you have theme or plugin options that you want to override a default setting, or if you’re creating a parent theme that may have elements overridden by a child theme.

Creating Filter Hooks

The apply_filters() function has three parameters: the name of the filter hook, the value which you want to filter (ie. the default value), and optional variables which you then pass to the functions hooked to the filter.

You can add a filter in your theme template files or inside a function that is hooked via an action hook. Let’s take a look at both options.

Returning to my compass_colophon() function, I convert this to a filter by adding its contents to my footer.php file inside the apply_filters() function like so:

echo apply_filters( 'compass_colophon', '
    <section class="colophon" role="contentinfo">
		<small class="copyright left">
			<?php echo compass_copyright(); ?>
			<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
			<?php bloginfo( 'name' ); ?>
			</a>
		</small><!-- #copyright -->

		<small class="credits right">
				Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://compass-design.co.uk">Compass Design</a>.
			</a>
		</small><!-- #credits -->
	</section><!--#colophon-->'
);

This outputs the code that I’ve set as the second parameter of my apply_filters() function.

However, I prefer not to add this directly to my theme template file, so I’ll add the filter to the function that I’m already attaching via an action hook.

So I add the compass_in_footer action to my footer.php file using the do_action() function as demonstrated above, and then I create a function in my functions.php file which is hooked to that action and contains a filter:

if ( ! function_exists( 'compass_colophon' ) ) {
function compass_colophon() {
    echo apply_filters( 'compass_colophon_filter', '
		<section class="colophon" role="contentinfo">
			<small class="copyright left">
				<?php echo compass_copyright(); ?>
				<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
				<?php bloginfo( 'name' ); ?>
				</a>
			</small><!-- #copyright -->
	
			<small class="credits right">
					Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://compass-design.co.uk">Compass Design</a>.
				</a>
			</small><!-- #credits -->
		</section><!--#colophon-->'
	);
}
add_action( 'compass_in_footer', 'compass_colophon' );

This means that I can now override the default content in one of three ways:

  • by creating a new function called compass_colophon() in my child theme, which overrides the function in my parent theme as that’s pluggable

  • by unhooking the compass_colophon() function from the compass_in_footer action hook and writing a new function which I attach to it in its place

  • by creating a new function which I then hook to the compass_colophon_filter filter hook, which overrides the value in my apply_filters() function

In real life you wouldn’t need to have this many options, so it’s more likely that you’d apply filters to part of the content in your function rather than the whole thing.

So I could create two filters, one for the copyright section and another for the credits:

if ( ! function_exists( 'compass_colophon' ) ) {
function compass_colophon() {
    
	echo '<section class="colophon" role="contentinfo">';
		
		echo apply_filters( 'compass_copyright_filter', '
			<small class="copyright left">
				<?php echo compass_copyright(); ?>
				<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
				<?php bloginfo( 'name' ); ?>
				</a>
			</small><!-- #copyright -->'
		);
		
		echo apply_filters( 'compass_credit_filter', '
			<small class="credits right">
					Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://compass-design.co.uk">Compass Design</a>.
				</a>
			</small><!-- #credits -->'
		);
	echo '</section><!--#colophon-->';
}
add_action( 'compass_in_footer', 'compass_colophon' );

Then I could either override the whole of my compass_colophon function by unhooking it or writing a new one in my child theme, or I could create a function hooked to the compass_copyright_filter or compass_credits_filter filter hook, to override each element individually.

Hooking Functions to Filters

To hook a function to a filter hook, you use the add_filter() function, which has two parameters: the name of the hook and the name of the function.

So to change the credits, I would write this function:

function new_credits() { ?>
    <small class="credits right">
		Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://rachelmccollin.co.uk">Rachel McCollin</a>.
			</a>
	</small><!-- #credits -->
<?php }
add_filter( 'compass_credits_filter', 'new_credits' );

This overrides the value set in my original compass_credits_filter filter hook with the content of my new_credits() function, but keeps everything else in the compass_colophon() function the same.

You can also specify priorities when hooking functions to filters, in exactly the same way as with action hooks. Functions with a lower priority will be run first.

Unhooking Functions From Filters

As with action hooks, you can also remove functions from filter hooks. You do this using the remove_filter() function, which has three parameters: the name of the filter hook, the name of the function, and the priority, which is mandatory if a priority was set when the function was originally hooked to the filter.

So to remove my new_credits() function, I use this:

remove_filter( 'compass_credits_filter', 'new_credits' );

The code output would then revert to the value I specified in my original apply_filters() function. So if I wanted to remove the new_credits() function and have nothing appear in its place, I’d have to add a new function. I then unhook the first function and hook my new function like so:

function no_credits() {
    return;
}
remove_filter( 'compass_credits_filter', 'new_credits' );
add_filter( 'compass_credits_filter', 'no_credits' );

Quick Recap

Lets take a birds-eye view of the whole thing to better understand how it fits together. Our primary aim in this tutorial was to output content to the footer and do it in a way that makes it very easy for others to modify the footer content.

The simplest way of doing this is to make a direct call to the function inside the footer.php file. However, this takes away some flexibility regarding the execution of the function and its output. One way to overcome this limitation is to use hooks and that’s what we did next.

We replaced our call to the compass_colophon() function with a call to do_action(). Keep in mind that the do_action() function did not make a call to compass_colophon(). It simply created an action hook at the location of do_action() call. The name of the action hook was compass_in_footer in our case.

The actual function that we want to call when the action compass_in_footer is triggered is specified by a call to the add_action() function. It took our hook name as its first parameter and our callback function as the second parameter. The first callback function that we attached to the compass_in_footer action was the compass_colophon() function.

We also have the option of attaching multiple callback functions to the same hook. This is exactly what we did when we added the compass_smallprint() function as another callback for the action hook. The order in which the functions are called is determined by the value of third parameter passed to add_action(). This allowed us to make sure that the function compass_smallprint() is executed after compass_colophon().

One advantage of using action hooks is that you can also stop any attached callback function from executing when an action is triggered by passing its name to the remove_action() function.

At this point, we had an action hook that was triggered in the footer and we called different callback functions attached to the action hook. Basically, we took some action and output content that we want to be placed in the footer of the website. Other people would also be able to unhook our function and attach their own callback functions to the action hook.

What if you wanted to only partially change the output of the footer without completely overriding or unhooking the original function? That’s when filters prove to be useful.

We create new filter hooks by using the apply_filters() function. It accepts two arguments at a minimum. The first one is the name of the filter hook which we set to compass_copyright_filter and compass_credit_filter in two of our apply_filters() calls. The second argument is the value that we want to filter or modify. We set it to the HTML code that shows the copyright and credit information.

We can then hook our own functions to these filters. We do this with the help of the add_filter() function. This function accepts two parameters. The first one is the name of the filter hook. The second parameter is the name of the callback function that you want to use to filter the value.

Another important thing to keep in mind is that the values you pass to apply_filters() only get filtered if there is a callback attached using the add_filter() function. Otherwise, the value passed as the second parameter to apply_filters() is kept unchanged.

We used this feature to change the credits but keep copyright information in the footer unchanged.

Final Thoughts

Understanding the difference between action and filter hooks and being able to use both of them effectively will give your theme and plugin development a boost. In fact, without using hooks of at least one type, you can’t write plugins at all, as the only way the code in your plugins is activated is via the action and filter hooks it’s attached to.

This guide showed you how to add the same functionality using a function, an action hook and one or more filter hooks, along with techniques for removing functions from hooks and advice on when each technique is more useful.

As well as hooking functions to your own action and filter hooks that you create, you can hook them to the actions and filters provided by WordPress, such as the wp_head action or the body_class filter.

Related posts:

  1. How To Create And Customize A WordPress Child Theme
  2. Kick-Start WordPress Development With Twig: Timber Image, Menu, and User
  3. How to Create a WordPress Landing Page Template
  4. 17 Best Shopify Templates for Your Online Store

Leave a comment

Your email address will not be published.