Filters in WordPress

Problem

You need to modify the output of a function in the WordPress Core, but you cannot modify the code of the function.

Example: If a single post is being viewed and it was published over five years ago, the output of the function get_body_class must include the class 'old-post'.

Filters

WordPress filters are a mechanism to allow the replacement of values produced by the code being run. A filter consists of:

• A name, also known as “tag” or “filter hook”
• A set of callbacks

The function add_filter adds a new callback to the set of callbacks of a filter. This process is known as “hooking”. The function remove_filter removes a callback from the set of callbacks.

The function apply_filters triggers the filtering. Each callback receives the value produced by the previous one, or the initial value if it is the first callback, and returns an output. The result is the output of the last callback in the queue. If no callbacks were hooked to the filter, the initial value remains unchanged.

Available filters

The list of filters triggered by the WordPress Core is large. Plugins and themes can also create their own filters. Some filters are:

• 'the_title' —filters the title of a post
• 'post_link' —filters the permalink of a post
• 'body_class' —filters the list of body classes for the current page

To get a complete list, search the codebase for calls to the function apply_filters. Each call triggers a filter and the filter is documented in detail using PHPDoc comments. Below is a code that triggers the 'the_title' filter. It is located in the file post-template.php of the WordPress Core.

/**
 * Filters the post title.
 *
 * @since 0.71
 *
 * @param string $title The post title.
 * @param int    $id    The post ID.
 */
return apply_filters( 'the_title', $title, $id );

Example

The following code defines the function ns_add_old_post_body_class and hooks it to the 'body_class' filter. This filter is triggered at the end of the function get_body_class .

The result is that if a post is visited and it was published over five years ago, 'old-post' is added to the list of classes returned by get_body_class.

/*
 * Adds a custom class to the list of body classes, if required.
 */
function ns_add_old_post_body_class($classes){
    
    global $post;
    $is_old_post = is_singular('post') && ((time() - strtotime($post->post_date)) > YEAR_IN_SECONDS * 5);
    return $is_old_post ? array_merge($classes, array('old-post')) : $classes;
}
add_filter('body_class', 'ns_add_old_post_body_class', 10, 1);

Filters vs actions

Filters and actions have similarities. Both concepts make possible the injection of code and the writing of extensible code in WordPress. Their API is very similar. There are just slight variations in the naming of functions.

The difference is in purpose. Filters allow us to replace a value when the filter is triggered, whereas actions allow us to do something when the action is triggered.

Source code

The source code developed in this tutorial is available here.