WordPress Development Stack Exchange is a question and answer site for WordPress developers and administrators. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

I have been looking at the plugin API a bit more in depth recently and I was wondering what real differences there were between action and filter hooks. They both are events that receive data as a parameter and they seem to both be able to do the same things.

Obviously I see that actions are called when actions take place and filters are called when data is manipulated, but it seems to just be a semantic naming difference.

Besides semantics and what they are used for, what real differences are there between them?

share|improve this question
up vote 36 down vote accepted

Hi @Sruly:

You've pretty much answered your own question, but I'll elaborate a bit.

Action Hooks

Actions Hooks are intended for use when WordPress core or some plugin or theme is giving you the opportunity to insert your code at a certain point and do one or more of the following:

  1. Use echo to inject some HTML or other content into the response buffer,
  2. Modify global variable state for one or more variables, and/or
  3. Modify the parameters passed to your hook function (assuming the hook was called by do_action_ref_array() instead of do_action() since the latter does not support passing variables by-reference.)

Filter Hooks

Filter Hooks behave very similar to Action Hooks but their intended use is to receive a value and potentially return a modified version of the value. A filter hook could also be used just like an Action Hook i.e. to modify a global variable or generate some HTML, assuming that's what you need to do when the hook is called. One thing that is very important about Filter Hooks that you don't need to worry about with Action Hooks is that the person using a Filter Hook must return (a modified version of) the first parameter it was passed. A common newbie mistake is to forget to return that value!

Using Additional Parameters to Provide Context in Filter Hooks

As an aside I felt that Filter Hooks were hobbled in earlier versions of WordPress because they would receive only one parameter; i.e they would get a value to modify but no 2nd or 3rd parameters to provide any context. Lately, and positively however, it seems the WordPress core team has joyously (for me) been adding extra parameters to Filter Hooks so that you can discover more context. A good example is the posts_where hook; I believe a few versions back it only accepted one parameter being the current query's "where" class SQL but now it accepts both the where clause and a reference to current instance of the WP_Query class that is invoking the hook.

So what's the Real Difference?

In reality Filter Hooks are pretty much a superset of Action Hooks. The former can do anything the latter can do and a bit more albeit the developer doesn't have the responsibility to return a value with the Action Hook that he or she does with the Filter Hook.

Giving Guidance and Telegraphing Intent

But that's probably not what is important. I think what is important is that by a developer choosing to use an Action Hook vs. a Filter Hook or vice versa they are telegraphing their intent and thus giving guidance to the themer or plugin developer who might be using the hook. In essence they are saying either "I'm going to call you, do whatever you need to do" OR "I've going to pass you this value to modify but be sure that you pass it back."

So ultimately I think that guidance provided by the choice of hook type is the real value behind the distinction. IMO, anyway.

Hope this helps!

share|improve this answer
To me it seems like you could have just used filters for everything, since returning a variable is optional in PHP. Anybody knows why WordPress developers chose to have two separate terms? Is it purely for semantic reasons? Technically I can't see the need for it... – TheStoryCoder Jun 10 '15 at 7:27
@TheStoryCoder "Is it purely for semantic reasons?" It seems that is exactly what my answer explained, five (5) years ago...? – MikeSchinkel Jun 13 '15 at 23:13

If you look at the source for the add_action() core function, it's just a wrapper for add_filter() function...

And if you look at the do_action() core function, it's very similar to the apply_filters() core function, with one very key difference: it does not return a value.

So what does this mean? actions are like filters, except an action does not return a value, so you cannot modify data. It shows that it was simple to create the WordPress' action mechanism by simply copying the filter mechanism, and not returning a value. Basically, all you can do with an action is simply execute a function without modifying some value.

share|improve this answer

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.