WP-Mix

In this tutorial, we have two quick examples showing how to use WordPress filter and action hooks. First we’ll look at how to use filter hooks, and then action hooks.

Filter Hooks

In the function that should be filtered, include apply_filters() for any data that should be filtered. Consider the following example:

function shapeSpace_example() {
	$value_to_be_filtered = get_some_value();
	return apply_filters('shapeSpace_example_filter', $value_to_be_filtered);
}

Here we have a function that basically gets a value and then returns it. But notice on the return value we use apply_filters(). This gives us a hook to use for filtering the return data as desired. Here is an example showing how to “hook” into the shapeSpace_example_filter and filter the $value variable:

function shapeSpace_modify_example($value) {
	return '<h1>' . $value . '</h1>';
}
add_filter('shapeSpace_example_filter', 'shapeSpace_modify_example');

That’s all there is to it. Here we have a function that accepts the $value variable from the source function, wraps it in <h1> tags, and returns it back to the source function. So the end result is that the output of shapeSpace_example() is filtered by shapeSpace_modify_example(). The key is using apply_filters() in the source function and add_filter() with the filter function.

Note that both apply_filters() and add_filter() accept some additional parameters that may be required depending on usage. Check the Codex links below for more infos.

More info about filter hooks

• WP Codex – apply_filters()
• WP Codex – add_filter()

Action Hooks

Using an action hook to perform some action is similar to using a filter function to modify data. Consider the following example function:

function shapeSpace_example() {
	$value = get_some_value();
	do_action('shapeSpace_example_action', $value);
	return $value;
}

Here we have an example function that includes do_action(). This enables us to do anything before returning the $value variable. In the following example, we send an email whenever the action hook is fired:

function shapeSpace_do_something($value) {
	mail('email@example.com', 'Message', $value);
}
add_action('shapeSpace_example_action', 'shapeSpace_do_something');

As before, here we have a function that accepts the $value from the source function. We could do anything inside of this function, perform any functionality that is required. To keep it simple, here we simply send an email that contains the $value. The key here is hooking the function into the source function via add_action(), such that shapeSpace_example_action is the point at which our action function fires.

The terminology can be subtly confusing at first, but after playing with a few examples, the symmetrical logic behind action and filter hooks should just “click”.

Note that both do_action() and add_action() accept some additional parameters that may be required depending on usage. Check the Codex links below for more infos.

More info about action hooks

• WP Codex – do_action()
• WP Codex – add_action()