Wordpress - Difference Between Filter and Action Hooks?

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!

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.

In simple word's.

Actions are those PHP functions which execute the output.

Filters are those PHP functions which return the output.

Updated: We can extend any plugin which use the actions and filters without modifying there code. By adding filters and actions in our own theme or plugin.

---

How to use?

Action:

Check below simple examples in your theme functions.php file.

1. Example One: (Simple PHP example)

function test() {
     echo "Output";
}

test();

Above program print the output:

Output

[NOTE: Here test() simply call the function. And execute the callback function 'test'.]

---

2. Example Two: (Simple use of Action)

function test1() {
     echo "Output";
}
add_action( 'test', 'test1' );

do_action( 'test' );

Above program print the output:

Output

[NOTE: Here do_action('test') works like calling function. And execute callback function 'test1'.]

---

3. Example Three: (Another use of Actions)

function test2() {
     echo "Test 2";
}
add_action( 'test', 'test2', 1 );

function test1() {
     echo "Test 1";
}
add_action( 'test', 'test1', 2 );

do_action( 'test' );

Above program print the output:

Test 2Test 1

[NOTE: Here do_action('test') works like calling function. And execute callback functions on it's priorities.

Callback function 'test1' has priority 2 And 'test2' has priority 1. ]

If priorities are change like 'test1' with priority 1 And 'test2' with priority 2 then output will be:

Test 1Test 2

---

4. Example Four: (3rd party support) Add below code in functions.php

function test1() {
     do_action( 'test_before' );
     echo "Test 1";
     do_action( 'test_after' );
}
add_action( 'test', 'test1' );

do_action( 'test' );

Above program print the output:

Test 1

Now, Create sample plugin to check how it works for 3rd party Developer.

1. Create folder 'simple' in /wp-content/plugins/ directory.
2. Create file named 'simple.php' and add below code.

/*
* Plugin Name: Simple Plugin
*/
function test_callback_function() {
     echo "From plugin";
}
add_action( 'test', 'test_callback_function' );

Now, Activate our Simple plugin from WordPress admin dashboard.

Goto menu plugin and activate it.

After activate plugin above program print the output:

Test 1From plugin

[NOTE: If we add the priority for our plugin action from 1 to 9 then it print the output like:

From pluginTest 1

Because, WordPress consider the 10 priority by default for all the added actions.]

Filters

Check the below examples:

Simple PHP example:

$data = array( 'one', 'two' );
print_r( $data );

Above program print the output:

Array ( [0] => one [1] => two )

1. Example One: (Simple use of Filter)

$data = apply_filters( 'my_filter_name', array( 'one', 'two' ) );
print_r( $data );

add_filter( 'my_filter_name', function( $old_data ) {
     return array( 'three', 'four' );
});

Above program print the output:

Array ( [0] => three [1] => four )

Here, We have added filter my_filter_name and change the existing output array( 'one', 'two' ) with array( 'three', 'four' ) without changing the theme/plugin files.

---