Dorokhov.codes

06. Hooks: actions and filters

There are two types of hooks within WordPress: actions and filters. Actions allow you to add or change WordPress functionality, while filters allow you to alter content as it is loaded and displayed to the website user.

The key difference between actions and filters is that actions are usually used for executing functions and filters are usually used for manipulating data.

List of hooks

Actions

Hook Description
admin_head Fires in head section for all admin pages. The common usage is to include CSS (external via <link> or inline via <style>) or JS (external and inline via <script>).
admin_notices Prints admin screen notices. Details.
wp_head This hook is generally placed near the top of a page template between <head> and </head>. This hook does not take any parameters.

Plugin hooks

Activation

This hook (activate_PLUGIN_BASENAME) is run when you activate your plugin. You would use this to provide a function to set up your plugin — for example, creating some default settings in the options table.

register_activation_hook( string $file, callable $callback );

Deactivation

This hook (deactivate_PLUGIN_BASENAME) is run when you deactivate your plugin. You would use this to provide a function that clears any temporary data stored by your plugin.

register_deactivation_hook( string $file, callable $callback )

Uninstalling

This hook is used to clean up after your plugin is deleted using the WordPress Admin. You would use this to delete all data created by your plugin, such as any options that were added to the options table.

register_uninstall_hook( string $file, callable $callback )

Adding custom hooks

Action hooks

Define a hookable location (hook) for actions:

do_action('my_action_hook');

Attach an action (some function) to the action hook:

add_action('my_action_hook', 'my_function_to_execute');

function my_function_to_execute() {
    // some commands
}

Also, there are two useful functions for action hooks. First, has_action() which checks if an action has been registered for some hook:

has_action('my_action_hook', $function_to_check);

And the remove_action() function, which removes an action that was set with add_action().

remove_action('my_action_hook');

Filter hooks

Creating a hookable location (hook) for custom filters to tie into:

$some_value = apply_filters('my_filter_hook', $some_value);

Attach a filter (function) to the filter hook:

add_filter('my_filter_hook', 'my_function_to_execute');

function my_function_to_execute($value) {
    // some manipulations with the $value
    return $value;
}

We can check if a filter (some function) has been registered for a hook:

has_filter('my_filter_hook', $function_to_check);

And we can remove a filter previously connected to apply_filters():

remove_filter('my_filter_hook');

About the difference between actions and filters

A filter is defined as a function that takes in some kind of input, modifies it, and then returns it.

An action is just a place where you call a function, and you don’t really care what it returns. The function is performing some kind of action just by being called.

Now, some actions have arguments too, but again, there’s still no return value.

So in a sense, a WordPress action is just a filter without the first argument and without a return value.

And there is a conceptual difference between an action and a filter. Filters filter things. Actions do not. And this is critically important when we’re writing a filter.

Additional sources