Difference Between Filter and Action Hooks?

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?

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!