WordPress Hooks Explained: Actions, Filters, and Custom Hooks

Q: What is the difference between do_action and apply_filters?

`do_action()` announces that something happened and runs every attached callback, ignoring anything they return. `apply_filters()` passes a value through every attached callback and returns the final result, so each callback must return the value, changed or not. If a filter callback forgets its `return`, the value becomes `null` and whatever it controls, such as post content or a price, disappears.

Q: Why isn't my remove_action working?

Three causes cover almost every case. The priority doesn't match the original `add_action()` call. The callback isn't the same reference, which is common with class methods registered as `array($this, 'method')` from an instance you can't reach. Or your removal runs before the original registration, so there is nothing to remove yet. Run the removal on a later hook (for example `init` or `after_setup_theme` at a higher priority) and use `has_action()` to confirm the exact priority first.

Q: What priority should I use for my hooks?

Use the default 10 unless you have a reason not to. Pick a lower number when your callback must run before others on the same hook, and a higher one (20, 99, or `PHP_INT_MAX` in rare cases) when it needs to see or override what other plugins did. If you find yourself bumping numbers repeatedly to win against another plugin, there is usually a later hook that fits better.

Q: Do hooks slow down WordPress?

Registering and firing hooks is cheap. The cost comes from what callbacks do: remote HTTP calls, uncached database queries, or heavy work on filters that run hundreds of times per request, such as `gettext` or `the_content` inside loops. Query Monitor shows the time each callback takes, which tells you which plugin to fix or replace.

Q: Do hooks still matter with block themes and the block editor?

Yes. Block themes replace PHP template files with HTML templates, but plugins, WooCommerce, the REST API, and the block editor itself all run on actions and filters. Block-specific filters such as `render_block` and `block_type_metadata` let you change block output and registration, and the core hooks above work the same way on classic and block themes.

WordPress hooks are the extensible architecture that allows plugins, themes, and core WordPress to communicate without modifying source code. Actions execute functions at specific points, while filters modify data before it's used or displayed.

What Are WordPress Hooks and How Do They Work?

WordPress hooks implement the observer pattern, allowing code to "listen" for events and respond accordingly. When WordPress core, plugins, or themes trigger a hook, all registered callbacks execute in priority order without requiring direct function calls.

The hook system consists of two main components: the hook registry (stored in $wp_filter global) and execution functions (do_action, apply_filters). When you register a hook with add_action or add_filter, WordPress stores your callback in a multi-dimensional array organized by hook name, priority, and unique identifier.

According to WordPress.org documentation, over 2,000 hooks exist in WordPress core (2024), providing extensive customization points throughout the request lifecycle. This extensible architecture enables the plugin ecosystem that powers over 43% of all websites.

Here's the fundamental hook registration process:

// Hook registration stores callback in $wp_filter global
add_action('init', 'my_init_function', 10, 1);

// WordPress core triggers the hook
do_action('init');

// Your callback executes at the appropriate time
function my_init_function() {
    // Your code here
}

Actions vs Filters: Understanding the Difference

Actions and filters serve distinct purposes in the WordPress architecture. Actions execute code at specific points without returning values, while filters process and return modified data.

Actions trigger at predetermined moments like user login, post save, or theme activation. They're perfect for tasks like sending emails, logging events, or initializing functionality:

// Action: Execute code when a post is published
add_action('publish_post', 'notify_subscribers');

function notify_subscribers($post_id) {
    $post = get_post($post_id);
    // Send notification emails
    wp_mail(get_subscribers(), "New Post: {$post->post_title}", $content);
}

Filters modify data before WordPress uses it. They must return a value and commonly adjust content, settings, or query parameters:

// Filter: Modify post content before display
add_filter('the_content', 'add_reading_time');

function add_reading_time($content) {
    $word_count = str_word_count(strip_tags($content));
    $reading_time = ceil($word_count / 200);
    
    return "<p>Reading time: {$reading_time} minutes</p>" . $content;
}

Aspect	Actions	Filters
Purpose	Execute code	Modify data
Return value	None (void)	Modified data
Common use	Events, notifications	Content modification
WordPress function	`do_action()`	`apply_filters()`
Registration	`add_action()`	`add_filter()`

Hook Priority and Argument Handling

Priority determines execution order when multiple callbacks hook to the same event. WordPress uses integer values where lower numbers execute first (default priority is 10).

// These execute in priority order: 5, 10, 15
add_action('wp_head', 'critical_css', 5);      // Runs first
add_action('wp_head', 'standard_meta', 10);    // Default priority
add_action('wp_head', 'analytics_code', 15);   // Runs last

The fourth parameter in hook registration specifies how many arguments your callback accepts. This prevents PHP warnings when hooks pass multiple parameters:

// Hook passes post ID and post object
add_action('save_post', 'process_post_save', 10, 2);

function process_post_save($post_id, $post) {
    // Access both parameters safely
    if ($post->post_type === 'product') {
        update_inventory($post_id);
    }
}

Complex priority management matters a great deal in plugin development. Consider this authentication flow:

// Security validation runs first
add_action('wp_login', 'validate_login_security', 1, 2);

// Standard login processing
add_action('wp_login', 'process_user_login', 10, 2);

// Analytics and logging run last
add_action('wp_login', 'track_login_analytics', 20, 2);

How to Remove WordPress Hooks

Removing hooks requires exact parameter matching with the original registration. You must specify the same callback, priority, and accepted arguments to successfully unhook functions.

// Original registration
add_action('wp_footer', 'unwanted_function', 15);

// Correct removal - matches priority
remove_action('wp_footer', 'unwanted_function', 15);

// Incorrect removal - different priority fails
remove_action('wp_footer', 'unwanted_function'); // Uses default 10, won't work

For class methods and anonymous functions, removal becomes more complex:

// Class method removal
class MyPlugin {
    public function __construct() {
        add_action('init', array($this, 'init_method'));
    }
    
    public function init_method() {
        // Plugin initialization
    }
    
    public function deactivate() {
        // Must use same array format
        remove_action('init', array($this, 'init_method'));
    }
}

// Anonymous function removal (store reference)
$callback = function() {
    // Anonymous callback
};
add_action('wp_head', $callback);

// Later removal
remove_action('wp_head', $callback);

According to WordPress Core Handbook, improperly removed hooks are a leading cause of plugin conflicts (2024). Always test hook removal in isolated environments before deploying to production.

Creating Custom Hooks for Plugins and Themes

Custom hooks enable extensibility in your plugins and themes. Create action hooks with do_action() and filter hooks with apply_filters() at strategic points in your code.

Custom Action Example for plugin lifecycle hooks:

class MyPlugin {
    public function activate() {
        // Standard activation tasks
        $this->create_database_tables();
        $this->set_default_options();
        
        // Custom hook for extensibility
        do_action('myplugin_activated', $this->get_version());
    }
    
    public function process_data($data) {
        // Before processing hook
        do_action('myplugin_before_process', $data);
        
        $result = $this->internal_processing($data);
        
        // After processing hook
        do_action('myplugin_after_process', $result, $data);
        
        return $result;
    }
}

// Other developers can extend your plugin
add_action('myplugin_activated', 'setup_integration');
add_action('myplugin_before_process', 'validate_external_data');

Custom Filter Example for data modification points:

class ThemeCustomizer {
    public function render_header() {
        $logo_url = get_theme_mod('logo_url');
        
        // Allow filtering of logo URL
        $logo_url = apply_filters('mytheme_logo_url', $logo_url);
        
        $header_classes = array('site-header', 'main-navigation');
        
        // Allow filtering of CSS classes
        $header_classes = apply_filters('mytheme_header_classes', $header_classes);
        
        echo '<header class="' . implode(' ', $header_classes) . '">';
        if ($logo_url) {
            echo '<img src="' . esc_url($logo_url) . '" alt="Site Logo">';
        }
        echo '</header>';
    }
}

// Theme users can customize output
add_filter('mytheme_logo_url', 'use_custom_logo');
add_filter('mytheme_header_classes', 'add_sticky_header_class');

Common WordPress Hook Patterns and Best Practices

Professional WordPress development follows established hook patterns that keep code compatible and maintainable. These patterns have evolved through years of community development and core WordPress iterations.

Conditional hook registration prevents unnecessary processing:

class AdvancedPlugin {
    public function __construct() {
        // Only register admin hooks in admin area
        if (is_admin()) {
            add_action('admin_init', array($this, 'admin_initialization'));
            add_action('admin_enqueue_scripts', array($this, 'admin_scripts'));
        }
        
        // Frontend-only hooks
        if (!is_admin()) {
            add_action('wp_enqueue_scripts', array($this, 'frontend_scripts'));
            add_filter('the_content', array($this, 'modify_content'));
        }
        
        // Universal hooks
        add_action('init', array($this, 'register_post_types'));
    }
}

Namespaced hook names prevent conflicts:

// Good: Prefixed with plugin name
do_action('mycompany_myplugin_data_imported', $data);
apply_filters('mycompany_myplugin_api_response', $response);

// Bad: Generic names cause conflicts
do_action('data_imported', $data);
apply_filters('api_response', $response);

Documenting your hooks makes them usable by other developers:

/**
 * Fires after successful payment processing
 * 
 * @since 1.0.0
 * @param int    $order_id    The processed order ID
 * @param float  $amount      Payment amount
 * @param string $gateway     Payment gateway used
 */
do_action('ecommerce_payment_completed', $order_id, $amount, $gateway);

/**
 * Filters product pricing before display
 * 
 * @since 1.0.0
 * @param float $price      The original price
 * @param int   $product_id The product ID
 * @param array $context    Pricing context (cart, single, archive)
 * @return float Modified price
 */
$display_price = apply_filters('ecommerce_product_price', $price, $product_id, $context);

Performance-focused hook implementation avoids heavy processing in frequently-called hooks. For sites with complex customizations, consider TopSyde's managed hosting, which includes AI-powered performance monitoring to identify problematic hooks.

Debugging WordPress Hooks with Query Monitor

Query Monitor provides comprehensive hook debugging without code modifications. Install the plugin to visualize hook execution, timing, and callback information across your WordPress site.

The Hooks panel shows:

Every hook triggered during page load
Which callback functions executed for each hook
The priority-based execution sequence
Time spent in each callback
The plugin or theme responsible for each hook

// Query Monitor automatically detects and displays these
add_action('init', 'heavy_initialization_function', 10);
add_filter('the_content', 'complex_content_processing', 5);
add_action('wp_footer', 'analytics_tracking', 20);

Advanced debugging techniques with Query Monitor:

Hook conditional logic:

// Query Monitor shows when conditionals prevent execution
add_action('wp_head', function() {
    if (is_single() && get_post_type() === 'product') {
        // This only appears in QM on single product pages
        echo '<meta name="product-page" content="true">';
    }
});

Performance bottleneck identification: Query Monitor highlights hooks exceeding performance thresholds. Look for callbacks taking >100ms or hooks firing >50 times per page load.

For production environments, Query Monitor's logging capabilities integrate with error monitoring services, providing ongoing hook performance insights without affecting site speed.

Performance Implications of Hook-Heavy Code

WordPress hooks introduce minimal overhead individually, but accumulative impact can significantly affect site performance. According to Automattic performance studies, sites with 50+ plugins average 2.3x more hook executions than lean installations (2024).

Performance impact analysis:

Hook Usage	Page Load Impact	Memory Usage	Database Queries
Light (0-100 hooks)	<50ms overhead	+2-5MB	No significant increase
Moderate (100-500 hooks)	50-200ms overhead	+5-15MB	+10-20% queries
Heavy (500+ hooks)	200ms+ overhead	+15-50MB	+20-50% queries

Optimization strategies:

// Bad: Heavy processing in frequently-called filter
add_filter('the_content', 'expensive_content_processing');

function expensive_content_processing($content) {
    // Database queries, API calls, complex calculations
    $external_data = wp_remote_get('https://api.example.com/data');
    $processed = complex_algorithm($content, $external_data);
    return $processed;
}

// Good: Cached processing with conditional execution
add_filter('the_content', 'optimized_content_processing');

function optimized_content_processing($content) {
    // Early return for non-target content
    if (!is_single() || get_post_type() !== 'article') {
        return $content;
    }
    
    // Cache expensive operations
    $cache_key = 'processed_content_' . get_the_ID();
    $cached = wp_cache_get($cache_key);
    
    if ($cached === false) {
        $processed = complex_algorithm($content);
        wp_cache_set($cache_key, $processed, '', 3600);
        return $processed;
    }
    
    return $cached;
}

Hook consolidation pattern:

// Bad: Multiple hooks for related functionality
add_action('wp_head', 'add_meta_tags');
add_action('wp_head', 'add_schema_markup');
add_action('wp_head', 'add_social_tags');

// Good: Single hook handling related tasks
add_action('wp_head', 'consolidated_head_additions');

function consolidated_head_additions() {
    add_meta_tags();
    add_schema_markup();
    add_social_tags();
}

For sites experiencing hook-related performance issues, managed hosting providers like TopSyde offer specialized WordPress optimization including hook profiling and automated performance recommendations.

Advanced Hook Techniques and Patterns

Professional WordPress development uses advanced hook patterns for complex functionality. These techniques support sophisticated plugin architecture while maintaining performance and compatibility.

Dynamic hook creation:

class MultiTenantPlugin {
    private $tenant_id;
    
    public function __construct($tenant_id) {
        $this->tenant_id = $tenant_id;
        
        // Create tenant-specific hooks
        add_action("tenant_{$tenant_id}_init", array($this, 'tenant_initialization'));
        add_filter("tenant_{$tenant_id}_settings", array($this, 'get_tenant_settings'));
    }
    
    public function trigger_tenant_event($event_type, $data = null) {
        // Dynamic hook firing
        do_action("tenant_{$this->tenant_id}_{$event_type}", $data, $this);
    }
}

Hook chaining for complex workflows:

class WorkflowEngine {
    public function process_order($order_id) {
        $order = new WorkflowOrder($order_id);

        // Stage 1: extensions can validate or veto the order
        $is_valid = apply_filters('workflow_validate_order', true, $order);
        if (!$is_valid) {
            do_action('workflow_order_rejected', $order);
            return false;
        }

        // Stage 2: each listener receives the previous listener's output
        $order = apply_filters('workflow_prepare_order', $order);
        do_action('workflow_before_fulfillment', $order);

        $result = $this->fulfill($order);

        // Stage 3: tell everyone the final outcome
        do_action('workflow_order_completed', $order, $result);

        return $result;
    }
}

// Extensions plug into any stage without touching the engine
add_filter('workflow_validate_order', function ($is_valid, $order) {
    return $is_valid && $order->total > 0;
}, 10, 2);

add_action('workflow_order_completed', function ($order, $result) {
    error_log("Workflow order {$order->id} completed");
}, 10, 2);

Each stage is a public extension point. A shipping add-on can hook workflow_prepare_order to attach rates, a fraud plugin can veto in workflow_validate_order, and neither needs to know the other exists. The filter chain passes the value along, so priorities decide who sees the data first.

Avoiding Infinite Loops in save_post

Calling wp_update_post() inside a save_post callback fires save_post again, which calls your function again, until PHP runs out of memory. Unhook yourself before the update and re-hook afterward:

add_action('save_post_product', 'myplugin_sync_excerpt', 10, 2);

function myplugin_sync_excerpt($post_id, $post) {
    if (wp_is_post_revision($post_id) || wp_is_post_autosave($post_id)) {
        return;
    }

    // Unhook to prevent recursion
    remove_action('save_post_product', 'myplugin_sync_excerpt', 10);

    wp_update_post([
        'ID'           => $post_id,
        'post_excerpt' => wp_trim_words($post->post_content, 30),
    ]);

    // Re-hook for the next save
    add_action('save_post_product', 'myplugin_sync_excerpt', 10, 2);
}

The priority passed to remove_action() matches the original registration. If the registration had used priority 20, a removal without the priority argument would fail and the loop would continue.

Run-Once and Context Checks

WordPress tracks hook execution, so you can read that state instead of keeping your own flags:

// Has this action already fired during this request?
if (did_action('woocommerce_init')) {
    // Safe to call WooCommerce functions now
}

// Are we inside a specific filter right now?
if (doing_filter('the_content')) {
    // Avoid calling apply_filters('the_content') again from here
}

// Which hook triggered this shared callback?
function myplugin_log_hook() {
    error_log('Fired by: ' . current_filter());
}
add_action('publish_post', 'myplugin_log_hook');
add_action('publish_page', 'myplugin_log_hook');

did_action() returns the number of times an action has run, so it doubles as a guard for code that must only run once per request. has_action() and has_filter() tell you whether anything is registered on a hook. Pass a callback as the second argument and they return that callback's priority, which is the fastest way to find the exact value to give remove_action().

Tracing Every Hook With the `all` Hook

WordPress fires a special all hook before every action and filter. It is too heavy for production, but on a staging site it gives you a complete count of what ran:

if (defined('WP_DEBUG') && WP_DEBUG) {
    add_action('all', function () {
        $hook = current_filter();
        $GLOBALS['myplugin_hook_counts'][$hook] =
            ($GLOBALS['myplugin_hook_counts'][$hook] ?? 0) + 1;
    });

    add_action('shutdown', function () {
        $counts = $GLOBALS['myplugin_hook_counts'] ?? [];
        arsort($counts);
        error_log(print_r(array_slice($counts, 0, 25, true), true));
    });
}

The log shows the 25 busiest hooks for one request. If gettext or option_* filters dominate the list, a plugin is probably doing work on every translated string or option read. Pair this with Query Monitor's per-callback timings to find the expensive callback, then move it behind an early return or a cache as shown in the performance section above.

Test hook changes on a staging environment before production. A wrong priority or a missing return in a filter can blank out content site-wide, and that is far easier to catch on a copy of the site.

Keep Reading on TopSyde

WordPress Multisite: Complete Setup and Management Guide. Learn how to set up and manage WordPress Multisite networks. Complete guide covering installation, domain mapping, performance, and hosting requirements.
Why Your Developer Hates Your Hosting (And What to Do About It). Tired of developer complaints about slow deploys and server limitations? Learn how cheap hosting kills productivity and what developer-friendly options cost less.
WordPress CI/CD Pipeline: Automated Testing and Deployment. Complete guide to WordPress CI/CD pipelines with GitHub Actions, automated testing, zero-downtime deployments, and rollback strategies for modern development.
WordPress Custom Post Types and Taxonomies Explained. Complete guide to WordPress custom post types: registration, taxonomies, ACF integration, REST API exposure, and query optimization for developers.
Full technical spec sheet
Our infrastructure stack

Frequently Asked Questions

What is the difference between do_action and apply_filters?

do_action() announces that something happened and runs every attached callback, ignoring anything they return. apply_filters() passes a value through every attached callback and returns the final result, so each callback must return the value, changed or not. If a filter callback forgets its return, the value becomes null and whatever it controls, such as post content or a price, disappears.

Why isn't my remove_action working?

Three causes cover almost every case. The priority doesn't match the original add_action() call. The callback isn't the same reference, which is common with class methods registered as array($this, 'method') from an instance you can't reach. Or your removal runs before the original registration, so there is nothing to remove yet. Run the removal on a later hook (for example init or after_setup_theme at a higher priority) and use has_action() to confirm the exact priority first.

What priority should I use for my hooks?

Use the default 10 unless you have a reason not to. Pick a lower number when your callback must run before others on the same hook, and a higher one (20, 99, or PHP_INT_MAX in rare cases) when it needs to see or override what other plugins did. If you find yourself bumping numbers repeatedly to win against another plugin, there is usually a later hook that fits better.

Do hooks slow down WordPress?

Registering and firing hooks is cheap. The cost comes from what callbacks do: remote HTTP calls, uncached database queries, or heavy work on filters that run hundreds of times per request, such as gettext or the_content inside loops. Query Monitor shows the time each callback takes, which tells you which plugin to fix or replace.

Do hooks still matter with block themes and the block editor?

Yes. Block themes replace PHP template files with HTML templates, but plugins, WooCommerce, the REST API, and the block editor itself all run on actions and filters. Block-specific filters such as render_block and block_type_metadata let you change block output and registration, and the core hooks above work the same way on classic and block themes.

Topics

plugin-management wordpress-performance developer-support wordpress-hosting managed-hosting

Rachel Nguyen

Senior WordPress Engineer

8+ years WordPress & WooCommerce development

Rachel is a senior WordPress engineer at TopSyde specializing in WooCommerce performance and plugin architecture. She has built and maintained high-traffic e-commerce sites processing millions in annual revenue.