How to Hook a Function to a Filter in WordPress

Background

WordPress filters allow the injection of code into a subject to replace specific data. A filter consists of a name and a set of callbacks. The function add_filter adds a new callback to the set of callbacks of a filter.

Triggering or applying a filter means that each callback hooked to the filter is given the opportunity to modify the value being filtered.

Syntax

add_filter($tag, $function, $priority, $accepted_args) adds the function $function to the set of callbacks of the $tag filter. $priority is the priority of $function within the set of callbacks. $accepted_args is the number of arguments that $function accepts.

$priority and $accepted_args are optional. By default, $priority is 10 and $accepted_args is 1. Lower $priority values mean earlier execution. Functions with the same priority are executed in the order in which they were added to the filter.

Functions hooked to a filter must return a result. They can take one or more parameters. The first one is the value being filtered. Other ones, if any, are to provide context.

Example

The following procedure is adaptable to any situation. For this case, suppose that the title of posts published over 10 years ago should be prefixed with '(Obsolete)', but only on the frontend.

Step 1: Search for the function that retrieves the value you need to filter.

The function get_the_title retrieves the title of a post.

Step 2: Verify that the function includes a filter.

Open the source code of get_the_title and verify that it triggers the 'the_title' filter at the end. This is a common pattern in WordPress to give external code a chance to modify the output.

/**
 * 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 );

Step 3: Develop a compatible function according to your needs or find an existing one.

The 'the_title' filter is triggered passing two arguments: the current title and the post ID. Therefore, any function hooked to this filter can take up to two parameters.

We need to create a custom function to prefix the title in specific cases. The function uses the contextual argument $id passed to the filter. This way, we can read the post matching the provided post ID and get its type and date.

/*
 * Adds a prefix to the title of a post, if required.
 */
function ns_add_obsolete_prefix($title, $post_ID){
    
    if(!is_admin()){
        $post = get_post($post_ID);
        $is_target_post = ($post->post_type == 'post') && ((time() - strtotime($post->post_date)) > YEAR_IN_SECONDS * 10);
        return $is_target_post ? __('(Obsolete) ', 'ns') . $title : $title;
    }
    return $title;
}
add_filter('the_title', 'ns_add_obsolete_prefix', 10, 2);

Step 4: Hook the function to the filter.

Use add_filter to add the function ns_add_obsolete_prefix to the set of callbacks of the 'the_title' filter.

add_filter('the_title', 'ns_maybe_add_obsolete_prefix', 10, 2);

Step 5: Test.

Change the date of a post to a date over 10 years ago. Visit the post on the frontend and verify that the title includes the '(Obsolete)' prefix.

Exercise

By default, if a user is logged in, WordPress shows a toolbar at the top of the frontend. Propose a solution to hide this toolbar for all users, except administrators.

Source code

The source code developed in this tutorial, including a possible answer to the exercise, is available here.