Most WordPress plugin tutorials introduce actions and filters as a pair - “actions do something, filters change something” - and leave it there. That description is correct but thin. It doesn’t explain why a filter that forgets to return its value silently breaks a page, why two plugins hooking the same action in the wrong order can corrupt data, or how WordPress actually stores and executes the hundreds of callbacks attached to a single hook on a typical page load. Understanding the mechanism, not just the syntax, is what separates code that works by luck from code that keeps working after five more plugins get installed.
What’s Actually Happening Inside WP_Hook
Every hook name in WordPress - wp_head, the_content, save_post, and every custom one you register - is backed by an instance of the WP_Hook class, stored in a global array ($wp_filter). When you call add_action() or add_filter(), you’re not doing anything conceptually different in either case: both functions are thin wrappers around the same underlying registration method, WP_Hook::add_filter(). That’s worth sitting with for a second, because it means the actions/filters distinction is a convention enforced by how do_action() and apply_filters() use the return value - not a difference in the storage or dispatch mechanism itself.
do_action( 'my_hook', $arg ) calls every registered callback and discards whatever they return. apply_filters( 'my_hook', $value ) calls every registered callback and threads the return value from each callback into the next one as its first argument, finally returning the last callback’s result to the caller. This is exactly why a filter callback that doesn’t explicitly return something breaks the chain: PHP functions with no explicit return statement return null, so the next filter in line (and eventually the code that called apply_filters) receives null instead of the value it expected. This single mistake - adding a filter, modifying a local variable instead of returning it - is one of the most common causes of content silently disappearing or options silently resetting on a WordPress site.
A Side-by-Side Example: Getting the Same Task Wrong as an Action, Right as a Filter
The clearest way to internalize the action/filter distinction is to see the same task implemented both ways. Say a plugin needs to append a disclaimer to every blog post’s content. Implemented incorrectly, as an action hooked to the_content:
// WRONG: the_content is a filter, not an action.
// This callback runs, but its return value is discarded,
// and it never actually modifies the displayed content.
function add_disclaimer( $content ) {
$content .= '<p>Disclaimer text.</p>';
// No return statement - this silently does nothing.
}
add_action( 'the_content', 'add_disclaimer' );Because the_content is a filter, hooking it with add_action() instead of add_filter() still technically runs the callback - WordPress doesn’t distinguish at registration time - but do_action() discards whatever the callback returns, so the modified $content variable never makes it back into the page. The correct version:
function add_disclaimer( $content ) {
$content .= '<p>Disclaimer text.</p>';
return $content;
}
add_filter( 'the_content', 'add_disclaimer' );This looks like a trivial difference on the page, but it’s the single most common category of “my hook isn’t working” bug reports in WordPress plugin support forums - a filter hooked with add_action(), or a filter callback missing its return statement. Both produce the identical symptom: the callback demonstrably runs (a var_dump or error_log inside it proves that), but the page never reflects the change, because nothing carried the modified value back to the caller.
Priority: How Callback Order Is Actually Resolved
Callbacks attached to the same hook are stored keyed by priority, and priorities are processed in ascending numeric order - lower numbers run first. The default priority is 10, which is why most third-party code you see uses 10 without thinking about it; that convention exists specifically so plugin authors have headroom both below (run earlier, priority 1-9) and above (run later, priority 11+) the typical middle ground.
Where teams get burned is when two unrelated plugins both hook save_post at priority 10, and their behavior depends on execution order that neither plugin controls. WordPress resolves ties at the same priority by registration order - whichever plugin’s add_action() call executed first (which usually means whichever plugin loaded first alphabetically or was activated first) runs first. That’s an implementation detail you should never rely on. If your callback genuinely needs to run after another specific plugin’s callback, the correct fix is an explicit priority difference, not hoping load order stays stable across updates.
// Runs before the default-priority callbacks
add_action( 'save_post', 'validate_custom_fields', 5 );
// Runs after the default-priority callbacks, once other plugins
// have already had a chance to modify the post
add_action( 'save_post', 'sync_to_external_service', 50 );The $accepted_args Trap
The fourth parameter to add_action() and add_filter() is easy to forget and produces one of the more confusing bugs in WordPress development. WordPress only passes as many arguments to your callback as you declared it should accept - and the default is 1, regardless of how many arguments do_action() or apply_filters() actually fired with.
// transition_post_status fires with THREE arguments:
// $new_status, $old_status, $post
do_action( 'transition_post_status', $new_status, $old_status, $post );
// This callback silently only ever receives $new_status -
// $old_status and $post are dropped because accepted_args defaults to 1
function log_status_change( $new_status, $old_status, $post ) {
// $old_status and $post are always null here
}
add_action( 'transition_post_status', 'log_status_change' );
// Correct version - explicitly declare how many arguments you need
add_action( 'transition_post_status', 'log_status_change', 10, 3 );This is why debugging a callback that seems to receive null for arguments that clearly aren’t null anywhere else in the codebase should always start with checking the accepted-args count against the hook’s actual do_action/apply_filters call signature in WordPress core or the plugin that fires it.
Removing Hooks: Why remove_action() Fails Silently
remove_action() and remove_filter() require the exact same callback reference, priority, and (for object methods) the exact same object instance that was used to register the hook. This is the single biggest source of “I called remove_action() and nothing happened” reports.
// If a plugin registered this hook with a class instance:
class Some_Plugin {
public function __construct() {
add_action( 'wp_footer', array( $this, 'inject_script' ), 20 );
}
}
// This will NOT remove it - you don't have a reference
// to the exact object instance the plugin created internally
remove_action( 'wp_footer', array( 'Some_Plugin', 'inject_script' ), 20 );If the plugin doesn’t expose its instance globally or via a filter, you frequently cannot remove that specific hook at all through the public API - the practical workarounds are hooking a later priority on the same action to counteract the output, or using a much later hook (like wp_footer at priority 999) with output buffering to strip unwanted markup. Neither is elegant, which is exactly why well-built plugins expose their object instances or provide their own dedicated removal filters for this reason.
Debugging Hook Order in Practice
When you genuinely don’t know what’s hooked to a given action or in what order, don’t guess - inspect it. Query Monitor (the WordPress debugging plugin most professional developers run locally) has a dedicated Hooks & Actions panel that lists every registered callback for the current page’s fired hooks, in execution order, with the exact priority and the plugin or theme file it came from. For a quick one-off check without installing anything, you can dump the raw registration data directly:
global $wp_filter;
if ( isset( $wp_filter['save_post'] ) ) {
error_log( print_r( $wp_filter['save_post']->callbacks, true ) );
}This prints every priority level and every callback registered at each one - genuinely useful when two plugins conflict and you need to know the actual execution order rather than assuming it.
Custom Hooks: Designing an API Other Developers Can Rely On
When you’re building a plugin meant to be extended, the hooks you expose are a public API, and they deserve the same design discipline as a REST endpoint. A few patterns that hold up over years of maintenance:
Fire a filter around every value a site owner might reasonably want to change - not just the big ones. A CSV export column list, an email “from” address, a cache duration - these are exactly the small decisions site owners want to override without forking your plugin.
$cache_duration = apply_filters( 'myplugin_cache_duration', HOUR_IN_SECONDS );Namespace every hook with your plugin’s prefix. A hook named before_save will eventually collide with another plugin’s identically-named hook, and there is no error or warning when that happens - both plugins’ callbacks just get called on whichever hook fires, silently mixing unrelated logic.
Pass enough context, not the bare minimum. A callback that only receives an ID often has to run an extra database query to get the object it actually needs. Passing the full object alongside the ID (accepting the minor memory overhead) saves every hooked callback from repeating that lookup.
Document accepted_args in a comment next to the do_action/apply_filters call itself, not just in a separate hooks reference doc that will drift out of sync. Future maintainers read the call site first.
How WordPress Core Itself Uses This Pattern
The clearest way to internalize good hook design is to look at how WordPress core exposes its own extension points, since the same conventions core follows are the ones third-party plugins are expected to follow too. wp_insert_post(), for instance, fires save_post as a general-purpose action, but also fires a more specific, dynamically-named variant - save_post_{$post_type} - so a plugin only interested in a specific custom post type doesn’t have to fire on every single post save site-wide and manually check the post type inside its own callback. This dynamic-hook-name pattern (a static hook plus a more specific one built from a variable, like a post type or taxonomy slug) is worth borrowing directly in your own plugins whenever a hook is likely to be relevant to only a subset of use cases - it lets other developers opt into exactly the scope they need instead of filtering broad, high-frequency hooks down to their specific case every time.
Core also demonstrates the filter-everything-worth-configuring principle at scale: excerpt_length, excerpt_more, upload_size_limit, and wp_trim_words are all small, specific filters around values that would otherwise require editing core files or a theme’s functions.php in a fragile way. None of these individually look important, but together they demonstrate the underlying discipline - anywhere a hardcoded value or default behavior might reasonably need to differ per site, core exposes a filter rather than forcing a workaround.
Testing Hook-Dependent Code
Code that depends on a hook firing correctly is notoriously easy to under-test, because a manual click-through test in the browser only exercises the specific order and combination of plugins active at that moment - it won’t catch a regression introduced when another plugin’s update changes its own hook priority six months later. WordPress’s PHPUnit testing framework (via the WP_UnitTestCase base class) lets you assert directly that a hook fired the expected number of times with the expected arguments, independent of any particular admin UI interaction:
public function test_custom_action_fires_on_publish() {
$fired = false;
add_action( 'myplugin_post_published', function() use ( &$fired ) {
$fired = true;
} );
$post_id = $this->factory->post->create( array( 'post_status' => 'draft' ) );
wp_publish_post( $post_id );
$this->assertTrue( $fired, 'Custom publish action should have fired.' );
}Writing even a small number of these tests for a plugin’s core hooks catches the specific class of regression that manual testing structurally misses - a refactor that accidentally moves a do_action() call inside a conditional it shouldn’t be inside, or a priority change that breaks an assumption another part of the same plugin was relying on.
Performance: Hooks Are Not Free
Every callback attached to a frequently-fired hook runs on every single request that triggers it, and on a busy hook like wp_head, wp_footer, or the_content, that can mean dozens of plugins each adding a small amount of overhead that compounds into a measurable slowdown across the whole site. Two patterns matter here. First, avoid attaching expensive work - a remote API call, a heavy database query - directly to a hook that fires on every page load if it’s only actually needed occasionally; gate it behind a specific condition (a page template check, a post type check) so the expensive branch only runs when it’s genuinely relevant. Second, be deliberate about which hook you choose for a given task - firing on init when you only need something on a specific admin screen means your code runs on every single front-end request for no reason, including for visitors who will never touch the admin area at all. Profiling tools like Query Monitor surface exactly which hooked callbacks are consuming the most time on a given page load, which is the fastest way to find an expensive callback that’s been silently firing on every request since it was added.
Real-World Architecture: Hooks as the Backbone of Plugin Design
Well-structured WordPress plugins use their own internal actions and filters as seams between major components, not just as the public extension API. A plugin handling e-commerce order processing, for instance, benefits from firing an internal action at each meaningful stage - order created, payment confirmed, fulfillment started, order completed - rather than calling every downstream function directly from one large procedural block. This buys two things: it makes the plugin’s own code easier to reason about, since each hooked function has a single, clear responsibility triggered by a specific event, and it means the exact same extension points a third-party developer would use are also the seams the plugin’s own core logic relies on, so there’s no risk of the public API drifting out of sync with what the plugin actually does internally. This event-driven pattern - treating a hook fire as a genuine domain event rather than a generic notification - is the single biggest difference between a plugin that stays maintainable at scale and one that becomes an increasingly fragile chain of tightly-coupled function calls as features get added over time.
Versioning Hooks Without Breaking Sites That Depend on Them
Once a plugin has real users, its hooks become a compatibility surface just like its database schema - removing a hook, or changing the number or meaning of its arguments, breaks every site whose custom code or third-party integration depends on the old signature, often silently, with no error message pointing at the actual cause. The safer pattern when a hook’s behavior genuinely needs to change: introduce a new, differently-named hook alongside the old one, fire both for a deprecation window (one or two major versions), and use _deprecated_hook() - the same core function WordPress itself uses to warn about deprecated hooks - to surface a clear notice in the debug log pointing developers at the replacement. This costs a small amount of extra code during the transition period, but it’s substantially cheaper than the support burden of sites silently breaking on update with no clear signal about why, which is what happens when a hook’s signature changes without warning.
Common Mistakes When Reading Hook Documentation
Even experienced developers misjudge a hook’s timing by trusting its name alone rather than checking exactly when in the request lifecycle it fires. A hook named init sounds like it should run at the very start of every request, but plenty of WordPress internals - taxonomy registration, some option loading - have already executed by the time init fires, which matters if your callback depends on something that isn’t set up yet. The reliable way to confirm a hook’s actual position in the lifecycle is a source-level trace through WordPress core’s wp-settings.php load order, or, more practically, dumping current_action() alongside a timestamp inside your own callback during development to see exactly where it lands relative to other known hooks - guessing from the hook’s name alone is a common, avoidable source of subtle plugin bugs that only manifest under specific timing conditions.
Security: Hooks Are Not a Trust Boundary
A callback attached to a filter receives whatever the filter passes, and WordPress does not sanitize that data on your behalf between hook calls. If you’re building a filter that ultimately outputs to the page, sanitize and escape at the point of output, not at the point of registration - you cannot predict every plugin that will hook in between and modify the value before it reaches the browser. Conversely, if you’re the one hooking someone else’s filter, never assume the value you receive is already safe; treat it as user input until you’ve verified otherwise, especially for filters that touch form submissions, URL parameters, or third-party API responses.
A Quick Decision Framework
When you’re not sure whether something you’re building should be an action or a filter, the test is simple: does the code that calls this hook need a value back? If yes, it’s a filter, and every callback attached to it must return a value of the same type it received. If the calling code just needs to notify the rest of the system that something happened - a post was saved, a user logged in, a cron job ran - and doesn’t care what any callback returns, it’s an action.
Getting this right up front avoids the awkward situation of realizing halfway through a plugin’s life that a hook fired as an action actually needs to let callbacks modify a value, which forces a breaking change to the hook’s signature and a support burden for every site that upgrades.