WordPress Actions and Filters: What’s the Distinction?

Motion and filter hooks are a essential component of the numerous WordPress APIs. With out them you happen to be limited as to what you can do in your themes and (particularly) your plugins.

But occasionally it can be easy to confuse the two, particularly in the scenarios when WordPress has the two an action hook and a filter hook with the similar name.

In this write-up I’ll outline action and filter hooks and describe the difference in between them, and I’ll display how to use them in your themes and plugins. I am going to also give some illustrations of when you could possibly use just about every.

When you happen to be including action and filter hooks to your code (or you might be hooking functions to them), it will help to fully grasp how steps and filters are termed by WordPress and what comes about in what order. I will not likely cover that in depth below as we have another tutorial that does that job.

Definitions and Variations

Let us start off with some definitions. I will define motion and filter hooks and features much too, so you can see the variance in between them all.

Capabilities

Functions are the very first matter most persons perform with when they’re mastering WordPress improvement if you’ve got included code to your theme’s features.php file, then you can have written a function.

Functions specify how some thing will materialize. You code a functionality to query data, to output material, or to accomplish many other jobs. You can simply call (execute) functions right in your theme’s template data files, or you can hook them to action or filter hooks. Features can also contain template tags such as conditional tags, to specify when the operate should really utilize.

I will clearly show you the diverse ways to execute functions later on in this report.

Action Hooks

Action hooks (or steps) are triggered when a little something requires area, these as loading a web page, a person logging in, or a custom made action that you determine in your theme or plugin.

You can incorporate your very own action hooks utilizing the do_action() operate, which I am going to show soon. Any capabilities you hook to that action will then run at that level in the code.

Filter Hooks

Filter hooks, or filters, management how a thing transpires or modify one thing which is now becoming output. You could use a filter to output metadata in a specific structure, to override text output by your plugin, or to reduce some thing from being exhibited at all.

You add filters in your code using the utilize_filters() operate, which I will demonstrate shortly. As the phrase ‘apply’ indicates, you apply filters to existing code, whereas an motion you develop working with do_motion() is vacant until you hook features to it.

Applying Capabilities, Actions, and Filters

Let us acquire a appear at some illustrations demonstrating how you use each and every of features, actions, and filters. Initially, we’ll appear at using capabilities directly in your code with no attaching them to a hook.

Contacting Features Straight

This is an case in point of a purpose that’s referred to as specifically in a template file. In my customer websites I increase a colophon in the footer, which incorporates copyright facts. This is the operate:

if ( ! function_exists( 'compass_colophon' ) ) 
perform compass_colophon()  ?>
    

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, and you can't override it because it's not pluggable. 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 (i.e. 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', '
    '
)
This outputs the code that I've set as the next parameter of my utilize_filters() function.
Having said that, I favor not to insert this right to my topic template file, so I will incorporate the filter to the perform that I am previously attaching by means of an action hook.
So I add the compass_in_footer motion to my footer.php file making use of the do_action() functionality as shown previously mentioned, and then I produce a perform in my features.php file which is hooked to that motion and contains a filter:
if ( ! function_exists( 'compass_colophon' ) ) {
purpose compass_colophon() 
    echo utilize_filters( 'compass_colophon_filter', '
'
)

insert_action( 'compass_in_footer', 'compass_colophon' )
This usually means that I can now override the default information in one of three techniques:

by developing a new function identified as compass_colophon() in my baby concept, which overrides the perform in my parent theme as that's pluggable
by unhooking the compass_colophon() purpose from the compass_in_footer motion hook and creating a new perform which I attach to it in its position
by building a new functionality which I then hook to the compass_colophon_filter filter hook, which overrides the benefit in my implement_filters() perform

In genuine life you wouldn't require to have this many selections, so it really is additional possible that you would use filters to aspect of the material in your function relatively than the entire matter.
So I could produce two filters, just one for the copyright portion and a different for the credits:
if ( ! perform_exists( 'compass_colophon' ) ) {
purpose compass_colophon() 
    
echo ''

increase_action( 'compass_in_footer', 'compass_colophon' )
Then I could both override the full of my compass_colophon operate by unhooking it or crafting a new one particular in my youngster topic, or I could generate a function hooked to the compass_copyright_filter or compass_credits_filter filter hook, to override each individual element individually.
Hooking Capabilities to Filters
To hook a purpose to a filter hook, you use the incorporate_filter() perform, which has two parameters: the name of the hook and the identify of the perform.
So to alter the credits, I would create this operate:
functionality new_credits()  ?>
    
Run by WordPress and built by Rachel McCollin.



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' )
Summary
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.