WordPress hooks: actions, filters, add_action, and add_filter

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

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 )

In all three functions the $file parameter is the plugin file that contains the header comment, so it is almost always __FILE__.

Example: activation and deactivation

A typical activation routine registers a custom post type and rebuilds the permalinks so that its URLs start working immediately:

function pluginprefix_setup_post_type() {
    // register the "book" custom post type
    register_post_type( 'book', ['public' => 'true'] );
}
add_action( 'init', 'pluginprefix_setup_post_type' );

function pluginprefix_install() {
    // trigger our function that registers the custom post type
    pluginprefix_setup_post_type();

    // clear the permalinks after the post type has been registered
    flush_rewrite_rules();
}
register_activation_hook( __FILE__, 'pluginprefix_install' );

And deactivation undoes it:

function pluginprefix_deactivation() {
    // unregister the post type, so the rules are no longer in memory
    unregister_post_type( 'book' );
    // clear the permalinks to remove our post type's rules from the database
    flush_rewrite_rules();
}
register_deactivation_hook( __FILE__, 'pluginprefix_deactivation' );

Example: uninstalling

Besides register_uninstall_hook(), there is a second way to run cleanup code:

To use this method you need to create an uninstall.php file inside the root folder of your plugin. This magic file is run automatically when the user deletes the plugin.

For example: /plugin-name/uninstall.php

The file must refuse to run when it wasn’t called by WordPress:

// if uninstall.php is not called by WordPress, die
if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
    die;
}

$option_name = 'wporg_option';

delete_option( $option_name );

// for site options in Multisite
delete_site_option( $option_name );

// drop a custom database table
global $wpdb;
$wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}mytable" );

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

• open_in_new Adam Brown’s WordPress Hooks Database .