WordPress Hooks – Actions and Filters

When a WordPress page loads, it brings together a bunch of things. Code, stylesheet, images and video all come together to form a page.

WordPress has bits of code spread throughout the source code that act as hooks. What these hooks do is, they let others hang in their own code.

These code blocks are easy to identify. They are either marked as do_action or apply_filter.

There are two types of hooks – actions and filters. Actions can do stuff and filters can modify stuff.

You can use an action hook to add something new to the page or do something completely unrelated. It is up to you.

The wp_head is an action hook that is widely popular among WordPress developers for adding something new to the head section of WordPress.

In its simplest form, you can use an action hook like this –

add_action( 'wp_head', 'callback_do_something');

Here wp_head is the hook and callback_do_something can be any function that you create. Inside this function you will write code to do something.

function callback_do_something() {
   // do something
}

Do callback functions take arguments? Yes they do.

To find out the number and name of arguments for a hook, go to WordPress developer site and search the code base for the matching do_action() call.

For example, if you are hooking into save_post, a search would find it in post.php

do_action( 'save_post', $post_ID, $post, $update );

Then your add_action call would look like

add_action( 'save_post', 'callback_to_save_post', 10, 3 );

And your function would be

function callback_to_save_post( $post_ID, $post, $update ) {
  // do something here
}

The last two parameters in add_action are priority(10) and number of accepted arguments(3). Since you are using all the three parameter in your function callback_to_save_post, you have to use the last argument(3) as well.

The priority parameter has a default value (10). It can be any positive integer starting with 0. Suppose the action hook has 3 functions attached to it. Then the function with the lowest priority will execute first. If you do not want to change it, leave it at its default value of 10.

Typically you will put this code in a theme’s function.php file or in a plugin file.

There are similar other hooks availble from WordPress database.

You can use a filter hook to modify WordPress content. A WordPress post consists of title, content and meta data. There are filter hooks available for each of these.

The the_content is a popular content hook that can change the output of WordPress content.

You can use a filter hook like this –

add_filter('the_content', 'callback_modify_something');

Where the_content is the filter name and callback_modify_something is the name of the function that you create.

function callback_modify_something($value) {
  // modify the value

  return $value
}

Similar to action hooks, filters can also accept arguments. In fact, there should be at least one argument in a filter hook. This value is returned from the filter after doing modifications.

For example –

add_filter('the_content', 'change_the_content');

function change_the_content( $content ) {
   // modify the content and return it
   return $content;
}

This code also goes to a theme’s function.php file or to a plugin file.

You can apply the filter hooks to comments too. The comments_template filter can be used to insert a custom comments template in place of the default one.

There are similar other filter hooks available from WordPress database.

Most of custom WordPress templates make use of actions and filters.

Beside the default hooks that comes with WordPress, you can also create custom named actions and filters.

To do that you will need to first add the hooks to source code like this –

do_action('your_custom_action_hook') for action hooks
apply_filter('your_custom_filter_hook') for filter hooks

This code goes to your any of your theme files (where you want the action or filter), or in your plugins file (if you are developing a plugin).

Then users can hook into that with –

add_action('your_custom_hook', 'custom_callback') for action hooks
add_filter('your_custom_hook', 'custom_callback') for filter hooks

Naming of custom hooks.

Custom action and filter hooks should have unique names. A good practice is to use the name of the organization as a prefix. I often use wdv_ as a prefix to my filters and actions. It avoids conflict with other similarly named hooks.

For example I would use –

do_action('wdv_post_wp_head') for a post wp_head custom action hook.

and I would use –

apply_filter('wdv_post_approved_comments') for a post approved comments custom filter hook.

If you have worked on a custom theme, chances are you have worked with hooks and filters.