WordPress hooks explained: How the WP_Hook class executes code

When I started building themes, I treated add_action and add_filter like magic spells. You drop a few lines into functions.php, and suddenly your site behaves differently. It wasn't until I had to debug a complex plugin conflict that I realized these functions are just thin wrappers around a much more robust engine: the WP_Hook class.

If you’ve ever wondered why your priority settings actually change when your code runs, or how WordPress keeps track of hundreds of callbacks without crashing, you’re looking at the core of the WordPress hooks system. Understanding this isn't just for core contributors; it’s for anyone who wants to write performant, predictable code.

The global storage mechanism

At the heart of everything is a global variable named $wp_filter. If you ever want to see the "state of the union" for your site, just var_dump($GLOBALS['wp_filter']) in a template. You’ll see a nested array structure that looks intimidating at first.

Every time you call add_action or add_filter, WordPress doesn't just store your function in a list. It checks if an instance of the WP_Hook class exists for that specific hook name. If it doesn't, it creates one.

Here is what that looks like in the source code:

PHP
#6A9955">// Inside wp-includes/plugin.php
if ( ! isset( $wp_filter[ $hook_name ] ) ) {
    $wp_filter[ $hook_name ] = new WP_Hook();
}
$wp_filter[ $hook_name ]->add_filter( $hook_name, $function_to_add, $priority, $accepted_args );

By using an object instead of a raw array, WordPress gains the ability to sort, iterate, and manage callbacks dynamically. This is a massive upgrade from how the system worked in the early 2000s.

Peeking inside the WP_Hook class

The WP_Hook class is where the heavy lifting happens. It doesn't just hold your callbacks; it organizes them into a multidimensional array sorted by priority. When you set a priority of 10, you’re telling the class exactly where to tuck your function into its internal $callbacks property.

The class stores your data in this shape:

• $callbacks[priority][callback_hash]
• The callback_hash is a unique identifier generated from your function or method, ensuring that we don't accidentally register the same logic twice.

This structure allows the WordPress action API and the WordPress filter API to perform a "lazy sort." They don't sort the entire list every time you add a hook; they wait until the hook is actually triggered. If you’re interested in how this affects your overall plugin architecture, check out my guide on Hooks and filters done right: Scaling your WordPress code.

Execution: How the magic happens

When do_action or apply_filters is called, the system retrieves the WP_Hook instance and triggers its apply_filters method. This is where the sorting happens. If the hooks haven't been sorted yet, the class calls ksort() on the priorities.

Then, it iterates through each priority level and executes the callbacks. This is why a priority of 5 always runs before a priority of 10.

I once spent about two days tracking down a bug where a plugin was firing a filter at priority 9, but my own code—also at priority 9—wasn't picking up the change. It turned out the other plugin was using an object method instead of a static function, and the callback_hash was being generated differently than I expected. That’s the beauty and the frustration of WordPress internals.

Why this matters for your code

If you're just starting out, you might want to review Your first WordPress hook: A beginner’s guide to customization to get the basics down. But as you scale, remember these three things:

1. Priorities are fixed: Once the hook starts executing, changing the priority of a function that is already in the queue won't do anything.
2. Memory usage: Every time you add a hook, you’re adding an object instance and a callback entry. On a massive site with 50+ active plugins, this can add up to a few extra megabytes of RAM per request.
3. Debugging: When things break, don't guess. Inspect the $wp_filter global. It is the single source of truth for every piece of code waiting to run.

I’m still learning new things about how the WP_Hook class handles edge cases, especially when it comes to recursive filters. Sometimes, I wonder if the performance overhead of the class structure is worth the flexibility, but given how much it simplifies the plugin ecosystem, it’s hard to imagine a better way. Keep your callbacks clean, watch your priorities, and don't be afraid to var_dump the globals when you hit a wall.

FAQ

Does the WP_Hook class make WordPress slower? Technically, yes, because objects have more overhead than arrays. However, the performance impact is negligible compared to database queries or external API calls.

Can I modify the WP_Hook instance directly? You can, but you shouldn't. Using the provided add_action and add_filter functions is the only "future-proof" way to interact with the system.

Why do we need a separate class for this? It allows for better encapsulation, easier sorting, and the ability to add features like remove_all_filters without destroying the entire registry.