WordPress Action and Filter Hooks

The WordPress Hook System

At the core of WordPress plugin development lies the hook system - a powerful mechanism that allows plugins to interact with WordPress core without modifying its code.

Think of WordPress as a railway system with many predetermined stations (hooks). Your plugin is like a new service that can connect to these stations to either gather information or add new functionality.

flowchart TB A[WordPress Core Execution] -->|Reaches Hook Point| B{Hook Check} B -->|No Callbacks Registered| C[Continue Execution] B -->|Callbacks Registered| D[Execute Registered Callbacks] D --> C

Two Types of Hooks: Actions vs. Filters

Action Hooks

Allow you to add functionality at specific points
Think of them as events you can respond to
Used when you want to DO something
Don't modify data; they perform operations


// Define an action callback
function my_plugin_custom_header() {
    echo '<div class="custom-header-banner">Special Announcement!</div>';
}

// Register the action
add_action('wp_head', 'my_plugin_custom_header');

Filter Hooks

Allow you to modify data before it's used
Think of them as data processors
Used when you want to CHANGE something
Must return the modified data


// Define a filter callback
function my_plugin_modify_title($title) {
    return '★ ' . $title . ' ★';
}

// Register the filter
add_filter('the_title', 'my_plugin_modify_title');

Analogy: If WordPress is a restaurant kitchen, action hooks are like signals that allow you to add new dishes to the menu, while filter hooks are opportunities to adjust the seasonings of existing dishes before they're served.

Hook Registration Functions

For Action Hooks


// Basic action registration
add_action('hook_name', 'callback_function', $priority = 10, $accepted_args = 1);

// With anonymous function (PHP 5.3+)
add_action('init', function() {
    // Do something on WordPress initialization
});

// With class method
add_action('wp_footer', array($this, 'footer_script'));

For Filter Hooks


// Basic filter registration
add_filter('hook_name', 'callback_function', $priority = 10, $accepted_args = 1);

// With anonymous function
add_filter('the_content', function($content) {
    return $content . '<p>Thanks for reading!</p>';
});

// With static class method
add_filter('the_title', array('My_Plugin_Filters', 'modify_title'));

Priority and Accepted Arguments

Priority (default: 10) determines the order of execution when multiple callbacks are registered. Lower numbers run earlier.

Accepted Arguments (default: 1) specifies how many parameters your callback function accepts.

Common Action Hooks

WordPress has hundreds of action hooks throughout its execution flow. Here are some essential ones:

Initialization Hooks

flowchart LR A[WordPress Loads] --> B[plugins_loaded] B --> C[setup_theme] C --> D[after_setup_theme] D --> E[init] E --> F[wp_loaded]

Plugin Lifecycle Hooks

register_activation_hook - When your plugin is activated
register_deactivation_hook - When your plugin is deactivated
register_uninstall_hook - When your plugin is deleted

Content Display Hooks

wp_head - Inside the <head> tag
wp_footer - Before the closing </body> tag
the_content - When post content is displayed
loop_start - Before WordPress starts the post loop
loop_end - After the post loop ends

Admin Hooks

admin_menu - When admin menus are being registered
admin_init - Early in admin page loading
admin_enqueue_scripts - For loading admin scripts and styles
add_meta_boxes - When registering meta boxes
save_post - When a post is saved

AJAX Hooks

wp_ajax_{action} - Handles logged-in AJAX requests
wp_ajax_nopriv_{action} - Handles logged-out AJAX requests

Common Filter Hooks

Filters allow you to modify data. Here are key filter hooks:

Content Filters

the_content - Filter the post content
the_title - Filter the post title
the_excerpt - Filter the post excerpt
get_the_excerpt - Filter excerpt before processing
comment_text - Filter comment content

URL and Query Filters

home_url - Filter the home URL
page_link - Filter the permalink for pages
post_link - Filter the permalink for posts
query_vars - Filter the allowed query variables
request - Filter the query request before it runs

Admin and Form Filters

manage_{post_type}_posts_columns - Filter admin columns for posts
wp_mail - Filter email parameters before sending
login_errors - Filter login error messages
upload_mimes - Filter allowed upload file types

Real-world Example: Modifying Post Content


/**
 * Add a read time estimate to post content
 */
function add_reading_time_to_content($content) {
    // Only add to main content on single posts
    if (!is_singular('post') || !is_main_query()) {
        return $content;
    }
    
    // Count words in the content (approximate)
    $word_count = str_word_count(strip_tags($content));
    
    // Calculate reading time (average 200 words per minute)
    $reading_time = ceil($word_count / 200);
    
    // Format the reading time message
    $time_message = '<div class="reading-time">';
    $time_message .= '<span class="dashicons dashicons-clock"></span> ';
    $time_message .= sprintf(_n('%d minute read', '%d minute read', $reading_time, 'my-plugin'), 
                             $reading_time);
    $time_message .= '</div>';
    
    // Add the reading time before the content
    return $time_message . $content;
}
add_filter('the_content', 'add_reading_time_to_content');

Creating Custom Hooks

You can create your own hooks in your plugin to make it extensible by other developers.

Custom Action Example


/**
 * Example custom action in an e-commerce plugin
 */
function process_order($order_id) {
    // Do initial order processing
    
    // Fire an action for others to hook into
    do_action('my_plugin_order_processed', $order_id);
    
    // Continue processing
}

Custom Filter Example


/**
 * Example custom filter in a content plugin
 */
function generate_author_box($post_id) {
    $author_id = get_post_field('post_author', $post_id);
    $author_name = get_the_author_meta('display_name', $author_id);
    $author_bio = get_the_author_meta('description', $author_id);
    
    $author_box = '<div class="author-box">';
    $author_box .= '<h3>' . esc_html($author_name) . '</h3>';
    $author_box .= '<p>' . esc_html($author_bio) . '</p>';
    $author_box .= '</div>';
    
    // Let other plugins modify the author box
    return apply_filters('my_plugin_author_box', $author_box, $author_id, $post_id);
}

Creating custom hooks is like designing a modular furniture system where others can add their own custom parts to extend functionality.

Hook Removal and Management

Sometimes you need to remove hooks added by WordPress core or other plugins.

Removing Actions


// Remove a simple action
remove_action('wp_head', 'wp_generator');

// Remove a class method action (needs same priority)
remove_action('save_post', array($some_class, 'save_post_callback'), 10);

Removing Filters


// Remove a filter from wpautop
remove_filter('the_content', 'wpautop');

// Remove with custom priority
remove_filter('the_title', 'some_title_filter', 15);

Checking If Hook Exists


// Check if an action exists before adding
if (!has_action('wp_footer', 'my_footer_function')) {
    add_action('wp_footer', 'my_footer_function');
}

// Check if a filter exists
if (has_filter('the_content', 'wpautop')) {
    // The wpautop filter exists
}

Getting Hook Information


// Get all callbacks for a hook (returns array or false)
$callbacks = $wp_filter['hook_name'];

// Check priority of a registered function
$priority = has_filter('the_content', 'wpautop');
// Returns priority number or false

Advanced Hook Usage

Using Multiple Priorities

You can use priorities to control the order of execution:


// Run early (before most other hooks)
add_filter('the_content', 'my_plugin_add_banner', 5);

// Run at normal priority
add_filter('the_content', 'my_plugin_format_content', 10);

// Run late (after most other hooks)
add_filter('the_content', 'my_plugin_add_footer', 20);

This is like scheduling tasks through a day - early morning tasks, midday tasks, and evening tasks.

Conditional Hook Registration


// Only add hooks when needed
function my_plugin_init() {
    // Only add admin hooks when in admin area
    if (is_admin()) {
        add_action('admin_menu', 'my_plugin_add_menu');
        add_action('admin_init', 'my_plugin_register_settings');
    } else {
        // Frontend hooks
        add_action('wp_enqueue_scripts', 'my_plugin_frontend_scripts');
        add_filter('the_content', 'my_plugin_modify_content');
    }
    
    // Add hooks only on single posts
    if (is_singular('post')) {
        add_action('wp_footer', 'my_plugin_post_footer_script');
    }
}
add_action('init', 'my_plugin_init');

Passing Extra Data to Hooks


// Using use() with anonymous functions (PHP 5.3+)
function register_dynamic_hooks($post_type, $options) {
    $prefix = $options['prefix'];
    
    add_filter("the_{$post_type}_content", function($content) use ($prefix) {
        return $prefix . $content;
    });
}

Real-World Plugin Hook Integration

Let's see how hooks are integrated in a real-world plugin structure.

E-commerce Product Display Enhancement


class Product_Display_Plugin {
    public function __construct() {
        $this->register_hooks();
    }
    
    private function register_hooks() {
        // Admin hooks
        add_action('admin_menu', array($this, 'add_settings_page'));
        add_action('admin_init', array($this, 'register_settings'));
        
        // Product display hooks
        add_filter('woocommerce_product_tabs', array($this, 'add_custom_product_tab'), 10);
        add_filter('woocommerce_short_description', array($this, 'enhance_short_description'), 10);
        add_action('woocommerce_before_single_product', array($this, 'add_promo_banner'), 5);
        
        // Create our own hooks for extensibility
        add_action('woocommerce_after_add_to_cart_button', function() {
            do_action('product_display_after_add_to_cart');
        });
    }
    
    public function add_custom_product_tab($tabs) {
        // Add a new product tab
        $tabs['custom_tab'] = array(
            'title'    => __('Additional Info', 'product-display'),
            'priority' => 25,
            'callback' => array($this, 'custom_tab_content')
        );
        return $tabs;
    }
    
    public function custom_tab_content() {
        // Custom tab content
        $content = get_option('product_display_tab_content', '');
        
        // Allow other plugins to filter this content
        $content = apply_filters('product_display_tab_content', $content);
        
        echo wp_kses_post($content);
    }
    
    // Other methods...
}

// Initialize the plugin
$product_display = new Product_Display_Plugin();

This example shows a plugin integrating with WooCommerce through hooks, while also providing its own hooks for further extension.

Debugging Hooks

Debugging hooks can be challenging. Here are some techniques:

List All Callbacks for a Hook


function debug_hook($hook_name) {
    global $wp_filter;
    
    if (isset($wp_filter[$hook_name])) {
        echo "<pre>";
        print_r($wp_filter[$hook_name]);
        echo "</pre>";
    } else {
        echo "No callbacks found for hook: $hook_name";
    }
}

// Usage:
add_action('wp_footer', function() {
    debug_hook('wp_head');
});

Track Hook Execution


function track_hook_execution($tag) {
    add_action($tag, function() use ($tag) {
        error_log("Hook executed: $tag");
    }, 0);
}

// Track multiple hooks
track_hook_execution('wp_head');
track_hook_execution('wp_footer');
track_hook_execution('init');

Using Debug Bar and Query Monitor

Plugins like Debug Bar and Query Monitor provide detailed information about hook execution:

Which hooks fired on a page
What functions are connected to each hook
Hook execution order and timing

Best Practices for Working with Hooks

Performance Considerations

Hook callbacks should be lightweight and fast
Use conditional logic to avoid unnecessary processing
Be cautious with early hooks like 'plugins_loaded' as they run on every request
Avoid excessive hook nesting which can lead to performance issues

Organization and Documentation

Group related hooks together in your code
Document your custom hooks for other developers
Use consistent naming conventions for hook callbacks

Defensive Coding

Always check parameters and validate data in hook callbacks
Return appropriate values from filters (same type as received)
Handle cases where your hook might run multiple times


/**
 * Example of defensive hook callback
 * 
 * @param string $title The post title
 * @return string The modified title
 */
function my_plugin_filter_title($title) {
    // Early return if empty
    if (empty($title)) {
        return $title;
    }
    
    // Only modify single post titles
    if (!is_singular('post')) {
        return $title;
    }
    
    // Avoid double-processing
    static $processed_ids = array();
    global $post;
    
    if (isset($post->ID) && in_array($post->ID, $processed_ids)) {
        return $title;
    }
    
    $processed_ids[] = $post->ID;
    
    // Actual title modification
    return 'Modified: ' . $title;
}
add_filter('the_title', 'my_plugin_filter_title');

Practical Exercise

Hook Integration Challenge

Create a simple plugin that uses at least two action hooks:
- One to add content to the footer
- One to add an admin settings page
Create a plugin that uses at least two filter hooks:
- One to modify post content
- One to modify post titles
Add your own custom hook in a plugin and demonstrate how another plugin could use it

Advanced Challenge

Create a "hook inspector" plugin that allows you to:

List all hooks that fire on a specific page
Show all registered callbacks for each hook
Display the priority of each callback