WordPress Action Hooks
Description
The WordPress Hooks system is what makes WordPress so extendable, and allows you to build anything on the foundation of WordPress, from a blog to an online ecommerce platform.
In this lesson, you will learn about action hooks, how they work, how to choose the right hook, and how to use them in your code.
Objectives
After completing this lesson, participants will be able to:
- Understand what WordPress hooks are
- Differentiate between the two types of hooks available
- Register an action hook callback function to perform some task
- Register an action hook callback with an adjusted priority
- Register an action hook callback with a specified number of available parameters
- Learn where to find more information on action hooks
Prerequisite Skills
Participants will get the most from this lesson if they have familiarity with:
- Some experience with the PHP programming language
- A way to register action hook callbacks, either a child theme or a plugin
Readiness Questions
- Do you have a basic knowledge of the PHP programming language (variables, functions, etc.)
- Do you have a way to create a child theme or a plugin?
Slides
Materials Needed
- A local install of WordPress
- A child theme or plugin to work in
- A text or code editor
Notes for the Presenter
- Participants will need to have a local WordPress install set up.
- If they don’t have one LocalWP is about the most beginner-friendly option.
- Participants will need a child theme or plugin to code in.
- If they don’t have either, they can use a child theme or plugin generator plugin.
- Participants will need a text or code editor.
- VS Code is a good option
Lesson Outline
- Introduce the WordPress Hooks system
- Explain the different hook types, actions, and filters
- Demonstrate how to register an action hook callback function, by enabling Post formats using the after_setup_theme hook and the add_action function
- Explain how hook priority works, and show different examples of this on the after_setup_theme callback registration.
- Explain a hook can have multiple arguments passed to the callback function.
- Using the save_post action hook, demonstrate how it would be possible to pass one, or all three arguments to the callback function, to be used.
Exercises
Register the selected Post formats in a child theme
- Ask participants to create a child theme, and register their selected post formats in the child theme
- Ask participants to save some metadata on a post, once the post is saved. This can be done in the above child theme or a separate plugin
- Ask participants to adjust the priority of when the callback function that saves the metadata above is run.
Assessment
What are WordPress Hooks?
- A way to automatically save metadata when saving a post or page
- A way to trigger an action at a scheduled time
- A way to interact/modify a WordPress request at specific, pre-defined spots.
- A way to catch errors in WordPress
Answer: 3. A way to interact/modify a WordPress request at specific, pre-defined spots.
Which hook type allows you to modify data?
- Action
- Filter
Answer: 2. Filter
Which of the parameters in the add_action function allow you to change the hook callback priority?
- $hook_name
- $callback
- $priority
- $accepted_args
Answer: 3. $priority
Which of the parameters in the add_action function allow you to define the number of arguments the hook callback accepts?
- $hook_name
- $callback
- $priority
- $accepted_args
Answer: 4. $accepted_args
Additional Resources
- WordPress Hooks explained
- Actions Explained
- add_action function documentation
- WordPress Action reference
Example Lesson
Today we’re going to learn about a WordPress development concept called Action Hooks.
Introduction
Hooks allow your theme or plugin code to interact with or modify the execution of a WordPress request at specific, predefined spots. Hooks are what makes WordPress so extendable, and allow you to build anything on the foundation of WordPress, from a blog to an online ecommerce platform.
There are two types of hooks, action hooks, and filter hooks. These are more commonly known as actions and filters. In this tutorial, we’ll focus on actions, but check out the filters tutorial for more information on filter hooks.
As their name states, actions allow you to perform some action at a specific point. To better explain this, let’s look at an example.
One common activity you will need to accomplish if you develop WordPress themes is deciding which Post Formats to support and then enabling support for them in your theme.
To do this, the documentation indicates you need to use the add_theme_support function, and recommends that this be registered via the after_setup_theme action hook.
Let’s go to the point in the WordPress code where this hook is first defined, which is currently on line 576 of the wp-settings.php file.
do_action( 'after_setup_theme' );
Here the do_action function defines the action hook, with the hook name after_setup_theme
We can also read more about this hook, in the documentation.
Here we see that this hook is fired during each page load, after the theme is initialized, and is used to perform basic setup, registration, and initialization actions for a theme.
In order to make use of an action, you register a function in your code to a pre-existing action hook, which is known as a callback function.
To register your callback function on an action you use the WordPress add_action function.
You will need to pass the hook name and the name of your callback function as arguments to the add_action function.
Let’s take a look at what this looks like in a child theme’s functions.php file.
add_action( 'after_setup_theme', 'wp_learn_setup_theme' );
Next, create the callback function, and add support for your chosen Post Formats.
add_action( 'after_setup_theme', 'wp_learn_setup_theme' );
function wp_learn_setup_theme() {
add_theme_support( 'post-formats', array( 'aside', 'gallery' ) );
}
You can name the callback function anything you want, but it’s always a good idea to create it with a unique prefix.
If you create a new Post now in your WordPress dashboard, you’ll see the Post Formats select box appear in the block editor, and you can select the required Post Format. Here you can see the two post formats you enabled in your callback function.
As you can see from registering an action, you use actions to perform something, either enabling some already existing feature or adding something to the code execution.
Hook Priority
Let’s look at hook priority.
If you take a look at the documentation for add_action you will see two additional function parameters, after the hook name and callback function. The third parameter is the hook priority, which is an integer that defaults to 10. This means if you register an action in your code without specifying a priority, it will be registered with a priority of 10.
Hook priority allows you to determine the order in which your hook callback is run, relative to any other hook callbacks that may be registered on the given hook, either by WordPress core, or other themes or plugins.
Hooks run in numerical order of priority, starting at 1. It’s usually safe to leave the priority to the default of 10 unless you specifically want to change the order in which your callback function is run.
For example, in our after_setup_theme action example, you may want to make sure that the registered callback function is only run after any callbacks registered by WordPress core are run. Because WordPress core registers any hook callbacks with the default priority of 10, if you specify a priority of 11, you can make sure my callback function is run after any core callbacks have been completed.
add_action( 'after_setup_theme', 'wp_learn_setup_theme', 11 );
Alternatively, if you want to make sure the callback is run before WordPress core’s, you would set a lower priority, say 9.
add_action( 'after_setup_theme', 'wp_learn_setup_theme', 9 );
Often you might see callbacks being registered with a high priority, like 99, or 9999.
add_action( 'after_setup_theme', 'wp_learn_setup_theme', 9999 );
This is because the plugin or theme developer wants to be sure that this callback is run after all other callback functions. However, one can never know at what priority other third-party plugins or themes might register their callbacks.
Hook Parameters
The fourth parameter in the add_action function is the number of accepted arguments the callback function can accept.
In order to better understand how this works, let’s take a look at the save_post action hook. This hook is defined in the wp_insert_post function, which is the admin function that either adds or updates, a WordPress post or page.
Right at the bottom of this function, we can see the following piece of code:
do_action( 'save_post', $post_ID, $post, $update );
Here, the do_action function registers the action hook with three variables that are associated with the action, the $post_id, the $post object, and the $update boolean.
When defining an action hook using do_action, any number of possible arguments can be added. However, the number passed to the accepted arguments parameter determines how many of them are passed to the hook callback function.
If you look at the documentation for add_action you will see the default value for the number of accepted arguments is 1, which means that if you don’t specify a value for this parameter, the first argument will be available to be passed to the callback function.
In the save_post action, there are three possible variables to be accepted. If you register the callback without setting the number of arguments, only the first will be available in the callback function, in this case, $post_id.
add_action( 'save_post', 'wp_learn_amend_post_meta', 10 );
function wp_learn_amend_post_meta( $post_ID ){
}
In order to accept more of the available arguments, you need to specify the number of arguments to accept.
add_action( 'save_post', 'wp_learn_amend_post_meta', 10, 3 );
function wp_learn_amend_post_meta( $post_ID, $post, $update ){
}
Then you can use those arguments in your callback function
Being able to determine which arguments you need for your callback function, and setting the number in the hook registration is a valuable skill. For example, let’s say you wanted to save the date the post was saved as a piece of metadata on a post, using the update_post_meta function, you might only need the $post_ID.
add_action( 'save_post', 'wp_learn_amend_post_meta' );
function wp_learn_amend_post_meta( $post_ID ) {
update_post_meta( $post_ID, 'post_saved', date( 'Y-m-d H:i:s' ) );
}
However, what if you wanted to do this only when the post is updated? In this case, the hook has the $update variable, which if we look at the wp_insert_post code, is set to true if the post is being updated. So you would need to update your callback to accept all three arguments from the hook to use the $update variable on your code.
add_action( 'save_post', 'wp_learn_amend_post_content', 10, 3 );
function wp_learn_amend_post_content( $post_ID, $post, $update ) {
if ( true === $update ) {
update_post_meta( $post_ID, 'post_updated', date( 'Y-m-d H:i:s' ) );
}
}
You will notice that I’m using the same variable names for the arguments being passed to the callback, in this case, $post_ID, $post, and $update. This is not a requirement, and you can call them anything you want when you register your callback function, but it does make it easier to remember what each variable is for if you name them the same.
Hook Order
Depending on your specific requirements, you may first need to determine which action is the correct one to use. Fortunately, the WordPress Codex has an Action Reference, which is a list of action hooks available in WordPress, and in the order that they are run during different requests on a WordPress site. You can also find the full list of available hooks in the Developer Resources code reference, under Hooks.