WPGEARED2.0.
WordPress Development

WordPress hooks explained: actions vs filters

Published
Share Report:

A WordPress action lets a callback do something at a named point in a request. A filter lets a callback change a value and return it. Register the callback with add_action() or add_filter(), using the hook name documented by WordPress, a theme or a plugin.

The sample plugin below prints a footer note, changes automatic excerpt length and adds two custom hooks. You can follow each callback from registration to execution.

1. Separate the hook from its callback

A hook name is a string such as wp_footer. The callback is your function, such as wpgeared_hooks_footer_note. Registering the function connects it to the hook. The function does not run merely because you registered it.

Task Register a callback Trigger the hook
Do work at a named point add_action() do_action()
Transform a value add_filter() apply_filters()

For core hooks, WordPress already contains the trigger. For a custom hook, your code must supply the trigger as well as register the callback.

An action callback may produce output at a suitable output hook, send a notification or perform another task. Its return value is not how the action communicates a result. A filter callback receives a value and must return the value the next callback should receive. Printing it is not a substitute. The WordPress hooks handbook explains both contracts.

2. Create a small plugin to experiment with

Use a local or staging site and keep file access for recovery. Create wp-content/plugins/wpgeared-hooks/wpgeared-hooks.php, then paste this complete file. Do not add it to WordPress core or duplicate it in a theme.

<?php
/**
 * Plugin Name: WPGeared Hooks Examples
 * Version: 1.0.0
 */
defined( 'ABSPATH' ) || exit;

function wpgeared_hooks_footer_note() {
    $context = 'footer';
    $text = apply_filters( 'wpgeared_hooks_notice_text', 'Thanks for reading.', $context );
    echo '<p class="wpgeared-footer-note">' . esc_html( $text ) . '</p>';
    do_action( 'wpgeared_hooks_after_notice', $context );
}
add_action( 'wp_footer', 'wpgeared_hooks_footer_note', 20 );

function wpgeared_hooks_excerpt_length( $length ) {
    return 25;
}
add_filter( 'excerpt_length', 'wpgeared_hooks_excerpt_length', 20 );

function wpgeared_hooks_notice_text( $text, $context ) {
    if ( 'footer' === $context ) {
        return 'Thanks for visiting our site.';
    }
    return $text;
}
add_filter( 'wpgeared_hooks_notice_text', 'wpgeared_hooks_notice_text', 10, 2 );

function wpgeared_hooks_after_notice( $context ) {
    if ( 'footer' === $context ) {
        echo '<p class="wpgeared-footer-extra">' . esc_html( 'Come back soon.' ) . '</p>';
    }
}
add_action( 'wpgeared_hooks_after_notice', 'wpgeared_hooks_after_notice', 10, 1 );

Activate WPGeared Hooks Examples. Visit a front-end page whose theme calls wp_footer(). You should see the two small notes near the bottom of the page, although the theme controls their surrounding layout.

The example deliberately avoids database writes and form handling. Those tasks introduce permission checks, nonces and other concerns that should not be hidden inside a first explanation of callbacks.

3. Follow the action through the request

This line registers the main callback:

add_action( 'wp_footer', 'wpgeared_hooks_footer_note', 20 );

When the theme reaches the footer hook, WordPress calls wpgeared_hooks_footer_note(). That function prints its paragraph, then fires the custom action below it.

Printing is appropriate here because the hook is an output location. It would not be appropriate to copy this behavior into a shortcode callback, which is expected to return its markup. A hook's contract and timing matter more than the fact that both examples use PHP functions.

A custom theme that does not call the footer hook will not display the note. Directly calling do_action('wp_footer') in a test proves the callback can run, not that every theme includes that hook.

4. Use a filter to return a value

The excerpt_length callback returns 25. That changes the length used when WordPress generates an automatic excerpt through that filter. It does not rewrite the full post or necessarily shorten a manually supplied excerpt. A theme or block using its own excerpt logic may behave differently.

A conditional filter needs a return on every branch. The custom notice filter demonstrates that pattern:

function wpgeared_hooks_notice_text( $text, $context ) {
    if ( 'footer' === $context ) {
        return 'Thanks for visiting our site.';
    }
    return $text;
}

This is an explanation of the function already in the file, not another function to paste beneath it. For the footer context, the text changes. For another context, the incoming value survives unchanged. Forgetting the final return would replace that value with null instead of leaving it alone. See the filters handbook.

The rendering function escapes the final output. The filter works with text, and the renderer handles its placement in HTML.

5. Control priority and accepted arguments

In a registration call, priority controls order, not importance. A lower number runs earlier. Callbacks at the same priority run in the order they were registered. The default priority is 10, and the default accepted-argument count is 1, according to the function references checked in November 2026. add_action and add_filter document the signatures.

The custom filter specifies both values:

add_filter( 'wpgeared_hooks_notice_text', 'wpgeared_hooks_notice_text', 10, 2 );

It accepts two arguments because the trigger supplies both the text and context. Setting the count to 2 does not invent a second argument. The hook must actually pass it.

When debugging order, write down the callback names and priorities rather than repeatedly choosing a larger number. A callback at priority 20 still cannot use data that will only exist on a later hook. Priority orders callbacks within one hook execution, not the whole WordPress lifecycle.

6. Create a custom filter and action

Inside the renderer, this call creates the value-changing extension point:

$text = apply_filters( 'wpgeared_hooks_notice_text', 'Thanks for reading.', $context );

The result is assigned to $text. Calling apply_filters() without keeping or returning its result would discard the transformation.

After printing the notice, this call creates an event:

do_action( 'wpgeared_hooks_after_notice', $context );

The sample callback uses that event to print the second paragraph only in the footer context. The action does not return a replacement notice.

When designing a real custom hook, document what each argument means and whether callbacks are expected to return a value. Prefix its name to avoid collisions. Do not expose private records to unrelated callbacks simply because passing the entire object is convenient. The custom-hooks handbook covers these extension points.

7. Remove a callback at the right time

To practise removal, append the following to the same plugin file, without another PHP opening tag:

function wpgeared_hooks_remove_footer_note() {
    remove_action( 'wp_footer', 'wpgeared_hooks_footer_note', 20 );
}
add_action( 'init', 'wpgeared_hooks_remove_footer_note' );

The original callback was registered when the plugin loaded. The removal runs on init, after that registration and before the later footer output. It matches the original hook, function and priority. Both footer paragraphs disappear because the function that triggers the second custom action no longer runs.

This timing is specific to this sample. A theme may register its callback later, so removing it earlier cannot work. Removal also cannot undo output or other work that already happened during the current request. Consult the relevant registration code rather than treating init as a universal removal hook. The remove_action reference lists the matching requirements.

Named callbacks are convenient here. If the original callback is an anonymous function, removing it requires the same callable instance, not a new anonymous function with identical text.

8. Find the hook that actually runs

Start with the official code reference, then read the source around the do_action() or apply_filters() call. Check when it happens, which arguments it supplies and whether the filtered result is used.

On a development or staging site, Query Monitor's Hooks panel can help inspect hooks and callbacks involved in the current request. Its own documentation describes the panel. It is not an exhaustive list of every hook that could run on every screen.

Theme-specific placement hooks are a separate layer. For example, the Kadence hooks guide covers locations provided by that theme, not names you can assume exist in all WordPress installations.

Check the result and undo the experiment

Before adding optional removal, confirm that the footer note appears once and the custom text replaces the original text. Check automatic excerpts on a page that actually uses them. Then enable removal and confirm the notes disappear while the rest of the page stays intact.

If nothing happens, check the hook spelling, callback spelling, registration timing and whether that request reaches the trigger. If a filter unexpectedly erases a value, inspect its return statements. If removal fails, compare the original callback identity and priority exactly.

Deactivate the sample plugin to remove its registrations. It does not store or delete content. If a syntax error prevents dashboard access, disable this sample folder through file access, correct the file and reactivate it on staging.

For a practical next use of an action hook, the wp_enqueue_scripts guide shows how to load CSS and JavaScript at the appropriate point instead of printing asset tags wherever a snippet happens to run.