A Guide to Actions and Filters in WordPress

WordPress comes with this built-in API that allows us to hook custom functionality into the rest of WordPress. We can provide that extra functionality through plugins or themes. These are called hooks and they are either actions or filtersActions allow us to run custom functions at a certain points of a request, while filters allow us to process and change data at these certain points.

The gist of the difference between actions and filters is:
Actions modify functionality; filters modify data.

WordPress makes heavy use of actions and filters for its own core functionality. Thus, we can use actions and filters to modify WordPress default functionality  or add our own on top of it. WordPress ships with an extensive lists of actions and filters that we, as developers, need to accustom ourselves with.

Usage

To employ actions and filters we need to use these two functions: add_action() and add_filter(). Both of them take four same arguments. The first two arguments are required and the two others are not and we won’t find ourselves using them a lot.

We hook custom functionality into WordPress like this:

add_action( 'hook_name', 'our_custom_action', [priority], [accepted_args] );

We use custom filters to transform data passed through WordPress like this:

add_filter( 'hook_name', 'our_custom_filter', [priority], [accepted_args] );

Actions

Actions are triggered at specific times during the request. In front-end it can be the time when the header or footer is loaded, giving us the ability to put our scripts at those sections. In back-end it can be the time when a post is published so that we can email our subscribers to notify them that a new post is published on our blog.

In the example action below the function changes default WordPress functionality by modifying the default image link type. By default it is set to Media File and we want it to default to None so we can save a couple of clicks when we insert images into a post. We hook this functionality in the admin_init action, which runs before any other hook when a user accesses the admin area.

function wpl_image_link_type() {
	$image_set = get_option( 'image_default_link_type' );

	if ( $image_set != 'none' ) {
		update_option( 'image_default_link_type', 'none' );
	}
}
add_action( 'admin_init', 'wpl_image_link_type' );

In such a fashion we run every action to modify WordPress default functionality or to add extra functionality to it.

Filters

Filters are functions which modify data that WordPress passes through them before showing that data to the user or inserting it into the database. Filters take in data and modify it and then return it so other filters can continue to process it.

In the example filter below, it default data by modifying the classes added to body by default through the body_class() function. Through this filter we append a class name to the list of default classes. Our theme relays on this class for showing the right color scheme based on what the user has saved in theme Customizer, i.e. either light or dark.

function wpl_body_class( $classes ) {
	// light or dark color scheme
	$classes[] = get_theme_mod( 'color-scheme', 'light' );

	return $classes;
}
add_filter( 'body_class', 'wpl_body_class' );

This is the way to filter data in WordPress. It’s very similar in structure to actions.

Custom Actions and Filters

Up to now we have talked about how we can use actions and filters that ship with WordPress. However, WordPress allows us to create our own actions and filters through plugins and themes. Custom actions and filters are helpful to make our themes and plugins extendible through child themes or other plugins without needing the edit the source files.

Custom actions and filters are created and called in the same way that core WordPress hooks are, through do_action() and apply_filters().

In the sample custom action hook below we want to add extra elements after the post content, we can add an action hook in our appropriate theme file like this:

do_action('after_content');

To hook into that action, so that we can, for example, show author bios or other elements like ads, we will have to run something like this:

function wpl_author_byline() {
	get_template_part( 'parts/author', 'byline' );
}
add_action( 'after_content', 'wpl_author_byline' );

On the other hand, for our custom filter hook, let’s say we want to add more color schemes to our default ones, dark and light that we talked above. In this case we want the default list of colors schemes to be extendible through a child theme. We will have have to create a custom filter hook like this:

function wpl_color_schemes() {
	$color_schemes = [ 
		'light' => 'Light',
		'dark' => 'Dark'
	];

	return apply_filters( 'wpl_schemes_filter', $color_schemes );
}

To hook into this filter and expend the list with more color schemes, we run something like this:

function wpl_add_color_schemes( $color_schemes ) {
	$color_schemes['yellow'] = 'Yellow';
	$color_schemes['blueish'] = 'Blueish';

	return $color_schemes;
}
add_filter( 'wpl_schemes_filter', 'wpl_add_color_schemes' );

The end result will be that on our Customizer now will show four color schemes rather then the original two.

Custom hooks into our themes or plugins make our code extensible so that we, or others, can modify and extend.

Keep learning

Actions and filters are a powerful tool at the hand of the developer and a great way to modify default WordPress functionality and to extend it. I  hope this article has taught you something new and valuable for your everyday work.