How to Hook a Function to a Filter in WordPress
The function add_filter
hooks 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.
If $tag
is 'all'
, WordPress executes $function
for all filters.
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.
Further reading
I recommend the other tutorials in this series to learn more about filters in WordPress.
- Filters in WordPress
- How to Hook a Function to a Filter in WordPress
- How to Trigger a Filter in WordPress
- How to Unhook a Function From a Filter in WordPress
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.
Comments