Physical Address

304 North Cardinal St.
Dorchester Center, MA 02124

Understanding and Using Hooks and Filters in WordPress

WordPress is a very popular blogging engine. It has also become very popular as a platform for various types of site which range from blogs to CMS to ecommerce sites. The success of WordPress majorly depends on the flexible and easily extendible architecture of WordPress. This lets the plugins and themes add functionality to WordPress without changing the core WordPress files.

Also two plugins can be enabled and can extend WordPress without interfering (almost) with each other. This is possible through the Action Hooks and filters which WordPress provides and the infrastructure it gives to define and use new action hooks and filters by your plugin. In this article we are going to understand the Action hooks and filters of WordPress and how we can use it in our plugins and themes.

Understanding and using $wpdb object in WordPress

Action Hooks and filters

In software, hooking in a general term which refers to some function or some code which can be plugged in and executed in the main flow at some specific points. WordPress on similar lines provides an infrastructure to plugin in and alter or extend the behavior of the main WordPress flow by letting plugins or themes hook into Action hooks or filters provided by WordPress.

Action Hooks

Action hooks are hooks which are fired during a particular event or action which happens in the flow of a particular request of WordPress. One can add his own function on such actions which can perform some additional task on that particular action. We are going to see how to use WordPress actions in our plugins/themes in the sections below.

Filters

The filters in WordPress are fired generally before any content is saved or displayed on screen. One can add a function on a filter and alter the content which will be saved or displayed on the browser. Generally filters pass the content as arguments and expect the return value to be the filtered content. We are going to see how to use WordPress filters in our plugins/themes in the sections below.

Using Action Hooks

Now we are going to see how one can hook into an already defined action hook either by WordPress core itself or some other plugin or theme. To hook your function into one of the action hook you will have to use the WordPress function add_action.

The add_action function can take four arguments. The first is the name of the hook in which you want to hook. The second argument is name of the function to call when the action hook happens. The third parameter is an integer defining the priority of the current function to be called when the hook is fired. The lower the number the earlier it will be executed and the last parameter is the number of argument your function can take.

Now let’s write a small code snippet which will make a post which has less than 15 characters in its title in draft status again. In case the post title is greater than 15 it will be allowed to publish.

For this we will have to hook into the post_publish action hook provided by WordPress core. This hook is fired whenever a post is published. The code to achieve this is as follows

[php]
function unpublish_post_with_less_characters_in_title($post_ID) {

$title = get_the_title($post_ID);
if(strlen($title) < 15 )
{
$my_post = array();
$my_post[‘ID’] = $post_ID;
$my_post[‘post_status’] = "draft";
wp_update_post( $my_post );

}
}
add_action ( ‘publish_post’, ‘unpublish_post_with_less_characters_in_title’ );
[/php]

As seen above here I use the add_action function in which the first argument is the name of the hook which in our case is publish_post. The second argument is the function name unpublish_post_with_less_characters_in_title which will be called when the action hook is fired.

This function just checks the length of the title and if it finds it less than 15 makes the post status as draft using the WordPress function wp_update_post.

If we add the above code in a plugin or functions.php of the theme and then add a post with the title smaller than 15 characters as shown below.

It will not be published but will be in draft status as seen below.

This way we can hook into any WordPress action hook which we would like to provide our functionality.

Making your plugin or theme extendible by Action hooks

Like the WordPress core call actions hook in which you can hook your function, you can also have action hooks which you call in your plugin and theme. This would make your theme and plugin extendible and other plugins can call their function on your hook. Let’s now see how you can have your own action hook.

Suppose you are making a theme and you want that any plugin can customize and run something before the loop in your theme is executed then you can add

[php]<?php do_action( ‘before_my_loop’ ); ?>[/php]

before your loop.

The do_action function takes two arguments, the name of the action hook to call and the arguments to pass to the function which will hook to your action hook.

You can find more details on do_action at the following link.

Once you have added the above code any plugin can hook into your hook using the add_action function we saw above as below

[php]
add_action( ‘before_my_loop’, ‘add_comment_before_loop’ );

function add_comment_before_loop()
{
echo "<b>Welcome to my blog</b>";
}
[/php]

Now if we see the home page you can see the text as follows.

Using Filters

The filter hook (like action hooks) are hooks in which you can add your function and your functions will be called when the hook is fired.
Filter hooks work on some content. They are fired just before some content will be used (either to put in the database or on the screen). The hooked function can alter the data when filter hooks are fired.

You can hook into a filter using the add_filter function. The arguments to add_filter are same as that of add_action.

Let’s now hook into the WordPress filter the_content which is called before any posts content is displayed on the screen. Let’s add a copy right note to every post by using this filter.

The code for using this filter is as follows

[php]
add_filter( ‘the_content’, ‘add_copy_right_note’ );

function add_copy_right_note( $content )
{

return $content . " <br>This content is copy righted material";
}
[/php]

In the above code we hook into the the_content filter and add the function add_copy_right_note to it. The content is passed to the function and we just append the copy right note and return it back.

Once we have added the above code the post content will be seen as below

Making your plugin or theme extendible by Filters

Like action hooks, we can use filter which WordPress core fires or we can also have filters in our plugin or theme which can be hooked into by other plugins. This can be achieved via the WordPress function apply_filters. The function apply_filters takes the arguments as the name of the filter, the value and some additional variables to be passed to the functions which hook into the filter. You can read more details about apply_filters at the following link.

So in case you are making a theme and you want your footer note to be customizable by any plugin I can add a footer note filter as follows in my footer.php of the theme

[php]
<?php
$footernote = ‘Powered By WordPress’;
$footernote = apply_filters( ‘the_footernote’, $footernote );
echo $footernote;
?>
[/php]

Now any plugin can add the following code to customize the footer note

[php]
add_filter( ‘the_footernote’, ‘change_footer_note’ );

function change_footer_note( $footernote )
{

return "<b>My Site Name</b>";
}
[/php]

Once this code is added by the plugin the footer note will be seen as follows.

Conclusion

The action and filter hooks form the core basics of the WordPress architecture. These make the WordPress platform completely extendible without having to modify the core WordPress files. In your plugin or the theme you can execute your code at specific actions of WordPress during the serving of a request without having to make any modification to any WordPress core files.

In addition to already defined action and filter hooks one can even add his hooks – action and filter which other plugins or themes can use. So have fun while hooking into WordPress.