Introduction to WordPress Actions and Filters

Posted by Ronald Huereca / June 30, 2019 /

The following is an excerpt from the upcoming WordPress and Ajax 3rd Edition book. Please visit wpandajax.com to subscribe to updates for the new book.
Ronald Huereca
Ronald Huereca

Actions and filters make up the foundation of WordPress development. Without them, you wouldn’t be able to execute code, change text, or customize WordPress to your liking.

Within this chapter, I will go over how actions and filters work and how to utilize them in your WordPress plugin.

WHAT IS AN ACTION?

A WordPress action allows you to execute code at a given point in WordPress. For example, if you browse the WordPress codebase, you’ll find a ton of actions available to execute. They’re usually found by searching for do_action, which may or may not pass arguments.

For example, there is an action for when your plugin is activated or deactivated. You can run a custom action when your plugin is activated or deactivated, or even when your plugin is uninstalled so you can clean up after yourself.

A very useful action is called plugins_loaded. This makes sure that all plugins have been loaded and that it is safe to execute your plugin code.

For example, here’s an example of instantiating a plugin class when all the plugins have been loaded that I stole from my WordPress plugin Simple Comment Editing, which uses a singleton.

add_action( 'plugins_loaded', 'sce_instantiate' );
function sce_instantiate() {
	Simple_Comment_Editing::get_instance();
} //end sce_instantiate

As you can see in the example above, I use the plugins_loaded action to call a procedural function called sce_instantiate (it’s important to prefix your functions!) and I call a static class instance called get_instance. Within this instance, I call the class constructor, which initializes all my hooks (aka, actions and filters).

Let’s look at another example of using an action inside of the Simple Comment Editing class that runs when a comment is posted.

add_action( 'comment_post', array( $this, 'comment_posted' ), 100, 1 );

When a comment is posted in WordPress, there is an action called comment_post which is executed. I use this action to run my own code when a comment is posted. Since I’m in a class context, I pass the $this variable as an array and call my own method named comment_posted. You may notice that I have 100 and 1 being passed in my action declaration. The 100 is the priority, which I set very high. The default is 10. The 1 I use is the number of arguments I expect the action to pass. I highly recommend browsing the WordPress codebase for do_action and notice that some actions pass an argument, while some don’t. It’s important to match the number of arguments that an action passes.

For example, if a do_action passes three arguments, I would then be doing:

add_action( 'some_wp_action', array( $this, 'callback_method' ), 10, 3 );

And then in my method I would expect these three arguments:

public function callback_method( $arg1, $arg2, $arg3 ) {
    // Run custom code here 
}

In summary, actions allow you to execute code whenever an action is available. You can run actions when a post is updated, add actions for Ajax calls (more on that later), and even run actions to initialize admin menus, REST calls, and much more.

Actions are an integral part of WordPress and we’ll be utilizing them a lot in this book.

What is a Filter?

Filters allow you to modify output. The output could be an object, string, boolean value, arrays, and much more.

Say for example, I have in my code this block:

$text = apply_filters( 'my_plugin_filter', 'This is text to modify' );

The use of apply_filters tells others that this is text that can be modified. Other plugin or theme developers could use that filter to modify the text I pass.

add_filter( 'my_plugin_filter', 'prefix_my_callback', 10, 1 );
function prefix_my_callback( $text ) {
    return 'My modified text';
}

Now the text that is displayed is the result of the applied filter. Feel free to search the WordPress codebase for all instances of apply_filters and you’ll find there is a lot to modify!

You can filter the main content, filter titles, and just about everything you can think of.

Let’s do another example where a user can modify the output of an array.

$approved_types = array(
	'comment',
);

/**
 * Filter: replyable_comment_email_batch_approved_types
 *
 * Allow extra comment types to have moderation emails sent.
 *
 * @since 2.2.5
 *
 * @param array  Approved Comment Types.
 */
$approved_types = apply_filters( 'replyable_comment_email_batch_approved_types', $approved_types );

This above example is from a plugin called Replyable. I needed to add extra comment types for an add-on, so I created a filter so that the add-ons could add extra comment types.

An example of me using that filter is as follows:

add_filter( 'replyable_comment_email_batch_approved_types', 'myprefix_approved_comment_types', 10, 1 );
function myprefix_approved_comment_types( $comment_types = array() ) {
    $comment_types[] = 'review';
    return $comment_types;
}

In the above example, I just add a new comment type to the passed array and return the new array.

Wrapping Up

Actions and filters make an integral part of WordPress development and it makes WordPress super customizable through third-party plugins and themes. While this is just an introduction, I’ll be giving you a trial-by-fire in later examples. Just keep a look out for do_action, apply_filters, add_action, and add_filter.

Posted in

Ronald Huereca

Ronald Huereca is the CEO of MediaRon LLC and enjoys WordPress plugin and theme development.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top