Porchy Web Development

So what’s the difference between WordPress filters and hooks?

Understanding what filters and actions do took me forever, ok, maybe not but longer than I’d care to admit at any rate. It wasn’t the fault of the resources I found, it was just that I couldn’t get my head around it. But one day, PING! I got it. Here is how I understand them. It’s simplified and, like all simplified things, loses out on some of the intricacies and nuances.

Filters: Give you something, allow you to change it then use the modified thing you return. You need to return values with filters.

Actions: Do something at a certain place. You don’t need to return values with actions.

Here is how a real life example would work, taken from the high pressure world of limerick writing.

The Filter

Phoebe and Lark are writing partners. Phoebe sends Lark the limerick

There once was a guy from Milan
Who had gotten a bit of a tan
But when he turned red
He stomped on the bed
And tantrummed just like a man

Lark reads the whole thing, edits it and sends it back to Phoebe as

There once was a god from Milan
Who had gotten a bit of a tan
The women loved him
And so did the men
There was no one who wasn’t a fan

In this analogy, Lark added a filter to Phoebe’s limerick. He took the whole limerick, edited it and handed it back to her.

An example of this in WordPress is the_content filter. This filter gives you the content, allows you to manipulate it, then requires it to be returned back so it can be used. You could, for example, get the content, then take every instance of the word “dog” and replace it with “not a cat” or add in a disclaimer at the end or simply replace all of the it on every page and post with “WHOOO”. The codex page linked previously has some good examples on how you can use it, too.

If you were to code Phoebe and Lark’s interaction and like to push analogies too far, it would go something like…

[code lang=php]
function the_limerick( ) {

// Build the limerick.
$limerick = 'There once was a god from Milan';
$limerick .= 'Who had gotten a bit of a tan';
$limerick .= 'But when he turned red';
$limerick .= 'He stomped on the bed';
$limerick .= 'And tantrummed just like a man';

// The filter 'the_limerick' will modify $limerick.
// If no filter is added, it will return $limerick.

echo apply_filters( 'the_limerick', $limerick );

// Now that there's a limerick, let's filter it.
// This function takes the value of $limerick.
function lark_the_limerick( $limerick ){

$new_limerick = str_replace( 'But when he turned red',
'The women loved him' );
$new_limerick = str_replace(  'He stomped on the bed',
'And so did the men' );
$new_limerick = str_replace(  'And tantrummed just like a man',
'There was no one who wasn't a fan' );

return $new_limerick;

// Filter $limerick using the function lark_the_limerick
add_filter( 'the_limerick', 'lark_the_limerick' );

The Action

Lark sends Phoebe a note asking her if she’d like to add anything to his poem

I love my sweet, said the boy
More so than all other toys
[note from Lark: Phoebe you can add something here if you’d like]
Because he brings me such joy

Phoebe comes, takes a look at the poem and writes in

But sugar is bad
So I gave it to Dad

And the final limerick reads

I love my sweet, said the boy
More so than all other toys
But sugar is bad
So I gave it to Dad
Because he brings me such joy

In this analogy, Phoebe added an action to Lark’s poem. She knew where she could do something and, right there, inserted a couple of lines. Lark took care of finishing off the poem.

An example of this in WordPress is the wp_footer action. Using this, you can stick in something that happens when the footer is loaded on each page. It should be in all decent themes and is generally right before the closing body tag. Here’s a list of four common action hooks for new plugin developers (I like the explanations which is why I’m including). I also came across this cautionary post on the init hook from Tuts+ which is quite good to know!
And again, if you were to code Phoebe contribution to Lark’s poem, it would go something like…

[code lang=php]
function the_poem( ) {

echo 'I love my sweet, said the boy';
echo 'More so than all other toys';

// Something can happen here.
do_action( 'the_poem' );

echo 'Because he brings me such joy';


// Now let's add in the missing bit.
function its_a_limerick_lark(){

echo 'But sugar is bad';
echo 'So I gave it to Dad';


// Add the action
add_action( 'the_poem', 'its_a_limerick_lark' );


Some answers to questions

Can I use filters to do things, not just filter things? Yes but don’t. Only use filters to filter whatever was passed to the function. See Otto’s post Actions and filters are NOT the same thing…  for some unintended consequences of someone using a filter to send emails.

Where is a list of the filters and actions in WordPress? Here is the Filter Reference and here is the Action Reference.

What’s a really good post on the support forums explaining this in more detail? I’m glad you asked. This from betsyv is excellent.

Join the newsletter

Subscribe to get the latest content by email.

Powered by ConvertKit. If you give me your email address, you may receive emails from me (JJ) about posts on this site. You can unsubscribe at any time.

Porchy Ltd is a company registered in England, no. 12035925

VAT Registration no. 331196421

Built with WPGraphQL and Gatsby

© 2019 - 2021