Actions & Filters

What are Actions & Filters?

Actions and Filters are the two types of "hooks" used in WordPress to modify the behavior or data inside a request.

// Actions
add_action(
    'init', // Hook name
    'my_init_function', // Name of callback function
    10, // priority
    1 // number of arguments
);

// Filters
add_filter(
    'the_content', // Hook name
    'my_modify_content_function', // name of callback function
    10, // priority
    3 // number of arguments
);
                

Actions at Large 👀

That code was only half of the story - which is why I would understand if you were confused!

// Hooking an action...
add_action('my_action', function(){ echo "Hello world!"; });

// Doing an action
do_action('my_action'); // "Hello world!"
                

The part they don't tell you is you have to DO the action too!

(same for filters)

Actions are good for

• enqueuing things (styles & scripts)
• registering things (custom post types + taxonomies, ajax endpoints, etc)
• modifying the context of the main query (the query that gets the content for the page from the database)

Action Example

add_action('wp_enqueue_scripts', function(){
    wp_enqueue_scripts('jquery');
    wp_enqueue_scripts(
        'my-script', // script handle
        get_template_directory_uri() . '/js/my-script.js', // script url
        ['jquery'], // dependencies
        '1.2', // version
        true // put in footer? Yep.
    );
});
                

Here's an example of enqueueing jQuery and our own custom script that relies on jQuery (at the exact point that we should).

Action Examples (continued)

add_action('pre_get_posts', function($query){
    if( !is_home() || !$query->is_main_query()){
        return;
    }

    // Only grab 5 posts...
    $query->set('posts_per_page', 5);
    // Did I say posts? Better make it products ;)
    $query->set('post_type', 'product');
});
                

Here we modify the main query to grab 5 posts, except make them products (just like woocommerce).

Welp! There goes my blog!

Action References

• Action Reference
• Admin Action Reference

WordPress core has many actions already built into it. Some plugins also leverage actions (although they mostly leverage filters...)

speaking of filters...

Filters

Filters leverage the exact same code to work as actions. The only difference is that filters expect a return value.

add_filter(
    'hello-filter',
    function($who){
        return 'Bob';
    }
);

// Without me hooking this filter, we'd get "Hello World!"
$who = apply_filters('hello-filter', 'World');
echo "Hello $who!"; // WITH it, we get "Hello Bob!"
                

We're waaaaayyyy past hello world!

Let's break it down

// Hooking a filter...
add_filter(
    'hello-filter', // hook name
    function($who, $galaxy, $universe){ return 'Bob'; }, // callback function
    10, // priority
    3 // Number of arguments to provide the callback
);

// Applying a filter
$who = apply_filters(
    'hello-filter',     // hook name
    'World',            // Current / default value
    'Galaxy',           // additional parameter
    'Universe'          // Another additional parameter
    // we can add additional parameters to this all day.
);
                

Filters (continued)

add_filter(
    'the_content',
    function($content){
        return str_replace(
            "hamburger",
            "cheeseburger",
            $content
        );
    }
);
                

Now every time the content says "hamburger" it will be replaced with "cheeseburger"

I don't know why...

Filter Reference(s?) No, just one.

• Filter Reference

There are many filters in WordPress core. Sometimes plugins also leverage them in order to be more customizable and extensible.

The downsides...

// Remember my "Bob" filter?
add_filter( 'hello-filter', function($who){ return 'Bob'; });

// What if in another plugin/theme...
add_filter('hello-filter', function($who){ return 'Lady'; });

// Who is $who now?!
$who = apply_filters('hello-filter', 'Tako');
                

This is where Priority comes into play...

Priority for Actions & Filters

The priority can help determine which comes first and which comes last. So does the order of registration within a priority level.

add_filter('hello',function($who){return 'Bob';}); // Prio 10

add_filter('hello',function($who){return 'Tako';}, 1000);

add_filter('hello',function($who){return 'Lady';}, 100);

echo "Hello " . apply_filters('hello', 'World'); // Tako wins!
                

Mwahahahahahaaaa!!!

That is all.

Any questions?