WordPress Hooks, Actions and Filters are the pieces which dock plugins to WordPress core. They are at the heart of each and every plugin. In this chapter, we explain this very important aspect of plugin development.

In the plugins’ main file, we use add_action() to to load admin module and similarly, many setup() methods of plugin class files use add_action(). Here is a snippet from class-options.php.


class Sos_Options {

    public function setup () {
        add_action( 'admin_init', array($this,'init_common_options') );
        add_action( 'admin_menu', array($this,'register_settings_page') );


Let’s understand what they mean.

WordPress Hooks

The first parameter of add_action() is the name the Hook. In the above code snippet admin_init and admin_menu are names of the hook.

WordPress Hooks, Actions, Filters.

For a moment, think of a WordPress without plugins. In such a scenario, WordPress simply runs its core and constructs the response and send it to the browser. To extend functionality, WordPress allows plugins and to do that it exposes some well defined points in its core and names them as hooks. Plugins can latch on to these points so that WordPress executes the plugin code and adds plugins’ output to the response.

The steps or hooks shown in the figure is just an illustration and there are many more hooks in between.

WordPress provides two types hooks.

  • Actions - These hooks are triggered by specific event thats takes place in WordPress such as display of admin screen, publishing of post etc.,

  • Filters - These hooks pass data through the functions at certain points. Using them, plugin functions can filter the data and return it to WordPress.

WordPress defines a large number of Action and Filter hooks and there is no need to remember much of them. However, as they are important to plugin development, we suggest to have a cursory look at Actions Reference and Filters Reference which lists the hooks defined by WordPress.


WordPress Actions

WordPress Actions are triggered by specific events at specified points in execution. We can attach or bind plugin functions to an action hook and these functions are known as action functions.

If we think that plugin is glued fully at a single point or hook, then we are wrong. It never happens that way!

WordPress Hooks, Actions, Filters.

Plugin never plugs to a single point or hook. It also means that WordPress never executes the plugin fully in a single step.

When WordPress plugs a plugin to its core then plugins’ functions and methods are attached to various action hooks. As WordPress execution progresses, it execute the attached actions (function or method).

WordPress Hooks, Actions, Filters.

As shown in the above figure, when plugin is loaded, function A is attached to init hook and function C to admin_menu hook as Actions. Later, when WordPress execution reaches init stage it executes function A and so on.

Method as Action

To attach a class method as an action, use following construct.

add_action( 'admin_init', array($this,'init_common_options') );

This attaches init_common_options() method of enclosing object $this as an action to admin_init hook. Remember to pass the reference to the method in an array as array($this, 'init_common_options').

In following code, a method is wrongly added without an array and this never get executed by WordPress Action framework.

// this method fails !!!

add_action( 'admin_init','init_common_options');  

Always check whether you have used the proper construct to pass the method as action!

Plugins use add_action() function to attach a function or method to the action hook. For most of the Action hooks, WordPress passes single parameter - the post or comment id - to the action function. Some actions take more than one parameter. Actions Reference provides information about the parameters. Baring few, majority action hooks don’t return values.

WordPress Filters

WordPress Filters are similar to actions except that, for filter functions WordPress passes data which may be modified or filtered in the function and returned.

A filter function takes unmodified data as input and returns modified data. If the data is not modified by the filter, then the original data must be returned so that other plugins can continue to filter the data.

Plugins use add_filter() function to attach a function or method to the filter hook.

Filters Reference provides information about the parameters and the type of data passed by WordPress to filter function.


WordPress Actions vs Filters.

For clarity, we list the features and differences of WordPress Actions and Filters.

Table 5.1. WordPress Actions vs Filters.

Actions Filters
Action is triggered when a specific event takes place. Filter passes data through an function which can modify or filter the data.
Usually post id or comment id is passed to action function. Some unmodified data is passed as input to the filter function.
Action functions call WordPress API to carry out some action such as database update, post meta data update, or echo some output so that it adds to the response. Filter functions modify or filter the data that is passed to the function by WordPress.
In most cases, returns post id or comment id and in some cases without any return value. Returns filtered data. If no change to data, then original data is returned. In some cases, null is returned to indicate that data has to be deleted or disregarded.

As further reading, we suggest you to refer WordPress Plugin API which is an excellent reference on WordPress Actions and Filters.

With that clear understanding of WordPress Hooks, Actions, Filters we move on to next chapter where we develop the plugin admin module.