Understanding WordPress Hooks: Actions vs. Filters Explained

Previously in this course, we discussed designing for MVC in WordPress and defining your plugin core class. Now that you have a clean, object-oriented structure, it’s time to make your code "talk" to WordPress.

WordPress isn't a traditional framework where you call functions in a linear script. It’s an event-driven system. Everything that happens—from rendering a page header to saving a post—is triggered by hooks. Without hooks, your plugin would exist in a vacuum, unable to interact with the core engine.

Actions vs. Filters: The Fundamental Difference

At their core, hooks are simply "places" in the code where WordPress allows you to intervene. They are split into two categories: Actions and Filters.

Actions (Do Something)

An action is an event that occurs at a specific point in the execution flow. When you "hook into" an action, you are telling WordPress: "When you reach this point, run my custom function." Actions do not return values; they perform tasks like sending an email, logging data, or modifying a global variable.

• Key function: add_action()
• Trigger: do_action()

Filters (Change Something)

A filter is a hook that allows you to intercept and modify data before it is used by WordPress or sent to the browser. Unlike actions, filters must return the modified value. If you don't return the value, you'll effectively break that part of the application.

• Key function: add_filter()
• Trigger: apply_filters()

As discussed in WordPress Plugin API: How Actions and Filters Actually Execute, understanding this distinction is the difference between writing clean, professional code and causing silent site crashes.

Hooking into WordPress: A Concrete Example

Let’s advance our Knowledge Base plugin. Suppose we want to add a custom message to the bottom of every post in our knowledge base. We need an action to "hook" into the content area and a filter to modify the content itself.

Hooking into an Action

We’ll use the wp_footer action to output a simple "Powered by Knowledge Base" message in the site footer.

PHP
#6A9955">// Inside your plugin's core class or a dedicated controller
public function init_hooks() {
    add_action('wp_footer', [$this, 'add_footer_message']);
}

public function add_footer_message() {
    echo '<p>Powered by our custom Knowledge Base plugin!</p>';
}

Hooking into a Filter

Now, let’s prepend a "Read more" label to the title of every post using the the_title filter.

PHP
public function init_hooks() {
    add_filter('the_title', [$this, 'prefix_knowledge_base_title'], 10, 2);
}

public function prefix_knowledge_base_title($title, $id) {
    #6A9955">// Check if we are in the main query and if it's our CPT
    if (in_the_loop() && get_post_type($id) === 'knowledge_base') {
        return 'KB: ' . $title;
    }
    
    #6A9955">// Always return the original title if we didn't modify it!
    return $title;
}

Hands-on Exercise

1. Open your plugin's main class file created in the previous lesson.
2. Create a new method called register_hooks.
3. Use add_action to hook into admin_notices to display a simple "Hello from my Plugin" message in the dashboard.
4. Use add_filter to hook into the_content and append a "Copyright 2023" string to the end of all posts.
5. Verify your changes by checking the WordPress admin and a single post on the frontend.

Common Pitfalls

• Forgetting the Return Value: This is the #1 error with filters. If your filter function doesn't return the data, the content will disappear. Always trace your return statements.
• Incorrect Priority: By default, hooks run at priority 10. If your code relies on data that another plugin modifies, you might need to change your priority (e.g., to 20). We will cover this in detail in the next lesson.
• Passing the Wrong Number of Arguments: Notice the 10, 2 in the add_filter example above? The 2 tells WordPress how many arguments your callback function expects. If you omit this, WordPress only passes the first argument, and your code will fail to access the post ID.

Recap

Hooks are the lifeblood of WordPress. Actions let you execute custom logic at specific moments, while filters allow you to transform data in transit. Mastering these allows you to extend WordPress without modifying core files, keeping your plugin architecture clean and maintainable.

Up next: We will look at how to control the execution order of your code using hook priorities.