Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 68 ยท Hooks: Actions and Filters

Priorities, Order and Removing Hooks

Learn how WordPress hook priorities and accepted_args work, why remove_action needs the same priority, how to remove class-method hooks, and how to inspect running hooks.

Once several plugins, a theme and WordPress core all hook into the same action or filter, one question matters more than any other: in which order do the callbacks run? The answer decides whether your filter sees the original title or one that another plugin has already rewritten, and whether your footer markup lands before or after somebody else's.

WordPress gives you two levers: the priority number you pass when you register a callback, and the registration order that breaks ties. It also lets you take callbacks away again with remove_action() and remove_filter(), but only if you can describe the callback exactly the way it was registered. This lesson covers both, plus the functions that tell you what is going on while hooks run.

If you have not met add_action() and add_filter() yet, start with Actions and Filters. The stand-in code below is plain PHP, so it runs here; the WordPress snippets are read-only because a real WordPress site cannot run on this page.

Priority: lower numbers run first

Both add_action() and add_filter() take the same four parameters:

PHP
add_action( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 );
add_filter( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 );

The default priority is 10. When a hook fires, WordPress runs callbacks in ascending priority order: 1 before 5 before 10 before 20. Callbacks that share a priority run in the order they were registered, which depends on which file loaded first. Plugins load alphabetically by folder, then the theme loads, so you should never rely on tie-breaking when order matters. Pick a distinct priority instead.

Typical conventions:

Priority Meaning
1 to 5 "Early": run before most other callbacks
10 The default, used by most code
11 to 20 "Late": run after default callbacks, often to override them
PHP_INT_MAX "Truly last": the final word on a filter value

The next example is a small stand-in for WordPress's hook system. It stores callbacks by priority and runs them in order. It is not the real implementation (core uses a WP_Hook class), but the behavior shown here matches how core orders callbacks.

PHP Priorities and registration order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The footer callbacks print in the order D, B, A, C: priority 1, then 5, then the two priority-10 callbacks in the order they were added. The filter chain trims first (priority 5), uppercases (10), appends the post ID (20) and wraps the result (30).

flowchart LR
    V["Original value"] --> P5["priority 5<br/>trim"]
    P5 --> P10["priority 10<br/>uppercase"]
    P10 --> P20["priority 20<br/>add post ID"]
    P20 --> P30["priority 30<br/>wrap in angle marks"]
    P30 --> R["Final value"]

A filter passes its value through every callback in priority order, so each callback sees the work of the earlier ones.

accepted_args: how many arguments you receive

A hook can be fired with several arguments, for example do_action( 'save_post', $post_id, $post, $update ). WordPress only hands your callback as many arguments as you declared in $accepted_args. The default is 1, so a callback that needs the second argument must say so:

PHP
add_action( 'save_post', 'myplugin_after_save', 10, 3 );

function myplugin_after_save( int $post_id, WP_Post $post, bool $update ): void {
    // all three values are available
}

If your PHP function requires more parameters than accepted_args provides, PHP 8 throws an ArgumentCountError. Declaring optional parameters with defaults avoids that, but declaring the right accepted_args is the cleaner fix.

For filters the first argument is always the value you must return. Extra arguments are context only: changing them has no effect on later callbacks.

One callback, one slot

WordPress identifies a callback by a unique ID built from the callback itself: the function name, the class and method, the object instance and method, or the closure object. Within one priority, that ID is the key. Registering the same callback twice at the same priority therefore does not run it twice; the second call simply replaces the first. Registering it at a different priority creates a second entry that does run.

The mini system above uses the same idea in callback_id(). The next example demonstrates it and everything about removal.

Removing hooks

remove_action() and remove_filter() undo a registration. Their signature mirrors the registration, minus the argument count:

PHP
remove_action( string $hook_name, callable $callback, int $priority = 10 ): bool;
remove_filter( string $hook_name, callable $callback, int $priority = 10 ): bool;

They return true when something was removed and false otherwise. Three rules explain almost every failed removal:

  1. The priority must match. A callback added at priority 20 is not removed by a call that defaults to 10.
  2. The callback must be the same one. For a method on an object you need the same instance, not a new object of the same class. For a static method, [ 'Class_Name', 'method' ] or 'Class_Name::method' works.
  3. The removal must run after the registration and before the hook fires. If you remove too early, nothing is registered yet; too late, the callback has already run.

An anonymous function (closure) is a special case: you can only remove it if you kept a reference to the very same closure object. A closure that was registered inline cannot be removed by anyone else, which is a good reason to prefer named functions or class methods in code that others may want to extend.

PHP Removal, has_action and current_filter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

After the removal calls, only the look-alike closure remains registered at priority 40, together with plain_footer. The last removal returns false because a new closure object is a different callback, even though its code is identical.

When to remove: timing matters

The most common mistake is removing a hook at the wrong moment. Consider a child theme that wants to cancel something its parent theme registers on after_setup_theme:

PHP
// Child theme functions.php
add_action( 'after_setup_theme', 'child_remove_parent_setup', 0 );

function child_remove_parent_setup(): void {
    remove_action( 'after_setup_theme', 'parent_theme_setup', 10 );
}

A child theme's functions.php loads before the parent's, so calling remove_action() at the top of the file would run before the parent has registered anything. The fix is to remove it from a hook that fires later but still before the target runs: here, the same hook at priority 0, which runs before the parent's priority-10 callback.

flowchart TD
    A["Child functions.php loads<br/>registers remover at priority 0"] --> B["Parent functions.php loads<br/>registers parent_theme_setup at 10"]
    B --> C["after_setup_theme fires"]
    C --> D["priority 0: remover runs<br/>remove_action succeeds"]
    D --> E["priority 10: parent_theme_setup<br/>is gone, never runs"]

Remove from a later point in time than the registration and an earlier point than the callback's own run.

The same pattern applies to plugins that unhook another plugin's callback: use a later hook such as init, or a later priority on the same hook.

Removing methods of objects you did not create

If a plugin registers add_action( 'init', [ $this, 'register' ] ) inside its constructor, you need that exact instance to remove it. Plugins that want to be extensible expose their instance (through a function or a global), and well-written ones use static methods or plain functions for hooks that others might need to remove. If you must unhook someone else's code, search the hook's registered callbacks and compare class names. Treat that as a last resort, because it depends on someone else's internals.

Other helpers worth knowing: remove_all_actions( $hook, $priority ) and remove_all_filters() clear everything on a hook (use them sparingly: they also remove other people's callbacks), did_action( $hook ) counts how often an action has fired, doing_action() and doing_filter() tell you whether you are inside a hook, and current_filter() returns the name of the innermost running hook. Callbacks shared between several hooks use current_filter() to find out which one called them.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You register a callback with add_action( 'init', 'my_setup', 20 ). Which call removes it?

    remove_action() uses a default priority of 10, so the priority must be passed explicitly (20 here) to match the registration. remove_all_filters() takes a hook name, not a callback name.
  2. 2. Two callbacks are registered on the same filter at priority 10. What decides which one runs first?

    At equal priority, callbacks run in registration order. Because that depends on file load order, use different priorities whenever order matters.
  3. 3. Why does remove_action( 'init', [ new My_Class(), 'run' ] ) fail to remove a hook registered with another instance of My_Class?

    WordPress builds the callback ID from the object instance and method name. A freshly created object has a different ID, so nothing matches.
  4. 4. A callback hooked with the default accepted_args needs the second argument of do_action( 'save_post', $id, $post, $update ). What happens in PHP 8 if the callback requires two parameters?

    WordPress only passes as many arguments as accepted_args allows (1 by default). A function that requires more throws an ArgumentCountError, so register it with the right count, for example 10, 3.

Summary

  • Callbacks run in ascending priority order; the default is 10, and ties run in registration order.
  • accepted_args controls how many hook arguments your callback receives; filters must still return the first one.
  • A callback is identified by function name, class and method, object instance or closure object; registering the same one twice at one priority keeps a single entry.
  • remove_action() and remove_filter() need the same callback and the same priority, and they run only after the registration and before the hook fires.
  • Closures can only be removed if you kept a reference; objects need the same instance.
  • has_action(), did_action(), doing_action() and current_filter() help you inspect hooks while they run.

Next, learn how to give your own plugin hooks that other developers can use: Creating Your Own Hooks.