Course: A Complete Introduction to the WordPress Hooks System

This course covers one of WordPress’s most crucial and widely used systems: Hooks, including both actions and filters. We introduce Hooks as an event-driven system, present the key concepts and terminology you need to understand this system, and dig deep into how to use hooks in your own code—including hooking in your own functions, removing previously hooked functions, and creating your own action and filter hooks for others to use.

Before we dive in, an invitation. If you want access to videos and additional code examples about WordPress hooks—and if you want to better understand WordPress development in general—then have a look at our full “learn WordPress development” course, Up and Running. It’s the best guide to WordPress development out there.

The Best Way to Learn WordPress Development

Get Up and Running Today

Up and Running is our complete “learn WordPress development” course. Now in its updated and expanded Third Edition, it’s helped hundreds of happy buyers learn WordPress development the fast, smart, and thorough way.

Here’s what they have to say:

“I think anyone interested in learning WordPress development NEEDS this course. Watching the videos was like a bunch of lights being turned on.” -Jason, WordPress developer

“Other courses I’ve tried nearly always lack clear explanations for why WordPress does things a certain way, or how things work together. Up and Running does all of this, and everything is explained clearly and in easy-to-understand language.” -Caroline, WordPress freelancer

Get Up and Running Now

1. Understanding Event-Driven Programming

The WordPress Event System: Understanding Hooks in the Broader Programming Context

Key Point: WordPress’s Hooks System is an Example of Event-Driven Programming

In event-driven programming systems, one system creates “events,” which as many other systems as necessary then respond to.

In event-driven programming systems, one system creates “events,” which as many other systems as necessary then respond to. This is precisely how WordPress’s hooks system works: WordPress core (and some themes and plugins) contains numerous with “hooks”—both action hooks and filter hooks—which you can use to “hook in” your own custom code at precise times in WordPress’s processing.

Key Point: Advantages of Event-Driven Systems

Event-driven architectures have several key advantages.

Highly Extensible

In event-driven systems, it’s quite easy for other people to supplement the behavior that the system was originally built with. In WordPress, WooCommerce is a powerful example: it turns WordPress’s blogging and website software into e-commerce software by inserting itself at key points in WordPress’s processing—all without changing the behavior of WordPress itself in any way.

Loosely Coupled

WordPress’s individual pieces of software are very “weakly coupled”: you can update WordPress itself without updating themes and plugins, and vice-versa, because the themes and plugins simply respond to events within WordPress’s processing, rather than integrating (coupling) with it in a deeper way.

This weak coupling means that each individual piece of software can move at its own pace, rather than moving in lockstep with the rest of the system. A more tightly coupled system could not support something like WordPress’s plugin architecture.

Appears Simple

The main code in an event-driven system (such as WordPress’s source code) appears simple, because it handles all external possibilities for extension by simply firing events that other code can respond to. These “event firings” (in WordPress, do_action() and apply_filters()) can usually be ignored as you read the code, making the remaining code itself appear rather simple and readable.

Key Point: Disadvantages of Event-Driven Systems

Event-driven systems have several notable drawbacks.

Apparent Simplicity can Hide Complexity

An event-driven system basically “passes” the complexity of extending it onto the code that responds to its events. In WordPress, this is primarily themes and plugins.

This code can be harder to write than in other systems under two particular circumstances:

1. If the event you’re responding to doesn’t pass you some data you need, then you must find a way to get it. This can lead to duplicated code and double work.
2. The interactions and time-based flow of an events system can itself cause problems. In WordPress, for example, it’s possible to try to “hook onto” the wrong event in WordPress and do something that you’re not yet allowed to do—or to end up doing something too late. In both cases, your code will not work, despite the code itself appearing quite reasonable.

Difficult to Debug

In an event-driven system, anything can change the state of the system by responding to a given event, and so event-driven systems are very difficult to debug.

WordPress developers will know this problem in, for example, the need to “deactivate all themes and plugins” to find the cause of a simple bug—since any of those pieces of code could be hooking into, and changing the state of, the system at the place where the bug is showing up.

2. WordPress Hooks: Actions and Filters

WordPress Hooks, Actions, and Filters: What They Do and How They Work

Key Point: Terminology

WordPress’s hooks system is the event-driven system that lets you add your own code into WordPress’s PHP processing.

The key terms in this system include hook, action, and filter, as well as related terms like action hook, filter hook, hooked function, action function, and filter function. WordPress’s own documentation uses these terms imprecisely, so it’s important to understand the proper definitions:

• A hook is a place in WordPress code that can get functions added to it. When you create a hook in WordPress, you give yourself and other developers the opportunity to add in additional functionality at that location.
• Hooked functions are the pieces of external code that are added into WordPress’s processing. In other words, these are the functions that get “hooked into” WordPress at the specific locations that its hooks make available.
• Two types of hooked functions exist: actions (also called “action functions”) and filters (also called “filter functions”). Filters modify existing output, while actions can do any type of custom functionality.
• Hooks come in two types—action hooks and filter hooks—according to which type of hooked functions they accept.

Because this terminology is very hard to visualize by itself, the article provides a lengthy analogy to clarify these relationships.

Key Point: Example Filter

The following is an example filter function:

add_filter('the_title', 'wpshout_filter_example');
function wpshout_filter_example($title) {
	return 'Hooked: '.$title;
}

This function hooks into the the_title filter hook, which fires anytime the title of a post is to be outputted to the page. It “hooks in” a custom filter function: the function called wpshout_filter_example.

The effect of this code, viewed in-browser, will be that “Hooked: ” is added before the title of all posts across the site.

Key Point: Example Action

add_action('wp_footer', 'wpshout_action_example');
function wpshout_action_example() {
	echo "WPShout was here.";
}

This function hooks into the wp_footer action hook, which fires just before the closing </footer> tag in a properly built WordPress theme. It “hooks in” a custom action function: the function called wpshout_action_example.

The effect of this code, viewed in-browser, will be that “WPShout was here.” is added to the bottom of the site footer.

3. Creating Extensible Code with apply_filters() and do_action()

How to Use apply_filters() and do_action() to Create Extensible WordPress Plugins

Key Point: Extensibility

WordPress’s hooks system allows code to extend other code. In the context of WordPress plugins, this creates the possibility of extensions: “plugins for plugins,” which extend existing plugins in specific ways, such as “Bookings for WooCommerce.”

To create an extensible theme or plugin, you create hooks for that plugin: specific points where external code may influence the plugin’s state and behavior.

Key Point: How to Create Hooks—apply_filters() and do_action()

WordPress hooks come in two flavors: filter hooks, which pass specific data to external code for modification, and action hooks, which allow external code to make changes of any type.

The function to create a filter hook is called apply_filters(). The function to create an action hook is called do_action().

An Example Filter Hook with apply_filters()

A very simple use of apply_filters() looks as follows:

$text_to_output = apply_filters( 'wpshout_sample_extensible_text', $text_to_output );

This allows external code to hook into the wpshout_sample_extensible_text filter hook. That external code would do so by calling add_filter(), and would use a custom filter function to modify the text given by $text_to_output. It would then pass the modified value back to the original code, which would proceed as normal with the modified value of $text_to_output.

An Example Action Hook with do_action()

A simple use of do_action() looks as follows:

do_action( 'wpshout_after_print_output_text' );

This allows external code to hook into the wpshout_after_print_output_text action hook. That external code would do so by calling add_action(), and would “hook in” in a custom function that could have any desired functionality. After that custom function (and all other action functions hooked to wpshout_after_print_output_text) finished executing, the original code would then proceed as normal.

The full article contains practical examples (with downloadable code) of both action and filter hooks, as well as an extension that responds to both.

4. Removing Hooked Functions with remove_action() and remove_filter()

https://wpshout.com/off-hook-practical-uses-remove_action-remove_filter/

Key Point: Removing Existing Hooked Functions

remove_action() and remove_filter() have one purpose: to cancel out existing calls to add_action() and add_filter() somewhere in your site’s code.

This is necessary when you want to remove existing functionality in a theme or plugin. Directly modifying the theme or plugin files themselves will cause you to lose your changes when you update the theme or plugin, so calling remove_action() and remove_filter() from an external plugin that you write yourself is a more robust approach.

Key Point: Example Use of remove_action()

A practical use of remove_action() looks as follows:

remove_action( 'woocommerce_before_shop_loop_item_title', 'woocommerce_template_loop_product_thumbnail' );

In a plugin you control, or in your theme’s functions.php, this code will cause WooCommerce Product featured images to disappear from your Shop page, since WooCommerce pulls in the code that displays these images using hooks rather than PHP templates.

Key Point: Example Use of remove_filter()

A practical use of remove_filter() looks as follows:

remove_filter( 'lostpassword_url', 'wc_lostpassword_url' );

In a plugin you control, or in your theme’s functions.php, this code will undo a WooCommerce function that redirects users who click “Lost Password” to a WooCommerce-created Login page rather than to the default WordPress login page at /wp-login.php.

Now You Know WordPress Hooks!

The key concepts above are the fundamentals you need to get started with WordPress’s very powerful hooks system. You’ll most commonly be using add_action() and add_filter() to add your custom code into WordPress’s processing, but knowing how to make your own code extensible—and even to remove other hooked functions—will seriously increase your power as a WordPress programmer.

Thank you for reading!