WordPress Hooks: Actions and Filters

Actions

Where an action hook (technically a do_action() function) exists in code running on WordPress, you can insert your code by calling the add_action() function and passing in the action hook name and custom function with the code you want to run:

do_action( $tag, $arg );

Here are the available arguments:

$tag

The name of the action hook being executed.

$arg

One or more additional arguments that are passed through to the function called from the add_action() function referencing this do_action() function. Say what? Keep reading…

You can create your own hook in a theme or plugin by adding your own do_action() functions. However, most of the time you will be using established hooks in the WordPress core or other plugins. For example, suppose you wanted to check whether a user was logged in when WordPress first loads up but before any output is displayed to the browser. You can use the init hook:

<?php
add_action( 'init', 'my_user_check' );

function my_user_check() {
	if ( is_user_logged_in() ) {
		// do something because a user is logged in
	}
}
?>

So what just happened? In the core of WordPress, there is an action hook, do_action(init), and we are calling a function called my_user_check() from the add_action() function. At whatever point in time the code is being executed, when it gets to the init action hook, it will run our custom my_user_check() function to do whatever we want before continuing on.

Filters

Filters are kind of like action hooks in the sense that you can tap into them wherever they exist in WordPress. However, instead of inserting your own code where the hook or do_action() exists, you are filtering the returned value of existing functions that are using the apply_filters() function in WordPress core, plugins, and/or themes. In other words, by utilizing filters, you can hijack content before it is inserted into the database or before it is displayed to the browser as HTML:

apply_filters( $tag, $value, $var );

$tag

The name of the filter hook.

$value

The value on which the filter can be applied.

$var

Any additional variables, such as a string or an array, passed into the filter function.

If you search the core WordPress files for apply_filters() you will find that this function is called all over the place, and like action hooks, it can also be added to and called from any theme or plugin. Anywhere in code running on your WordPress site that you see the apply_filters() function being called, you can filter the value being returned by that function. For our example, we are going to filter the title of all posts before they are displayed to the browser. We can hook into any existing filters using the add_filter() function:

add_filter( $tag, $function, $priority, $accepted_args );

$tag

The name of the filter hook you want to filter. This should match the $tag parameter of the apply_filters() function call for which you want to filter the results.

$function

The name of the custom function used to actually filter the results.

$priority

This number sets the priority in which your add_filter() function will run compared to other places in the code that might be referencing the same filter hook tag. By default, this value is 10.

$accepted_args

You can set the number of parameters that your custom function that handles the filtering can accept. The default is 1, which is the $value parameter of the apply_filters() function.

OK, so how would real code for this look? Let’s start by adding a filter to alter the title of any post returned to the browser. We know of a filter hook for the_title that looks like this:

apply_filters( 'the_title', $title, $id );

$title is the title of the post, and $id is the ID of the post:

<?php
add_filter( 'the_title', 'my_filtered_title', 10, 2 );

function my_filtered_title( $value, $id ) {
	$value = '[' . $value . ']';
	return $value;
}
?>

The preceding code should wrap any post titles in brackets. If your post title was “hello world,” it would now read “[hello world].” Note that we didn’t use the $id in our custom function. If we wanted to, we could have applied the brackets to only specific post IDs.