How to Hook a Function to an Action in WordPress
The function add_action
hooks a function to an action in WordPress.
Background
WordPress actions allow the injection of code into a subject to perform custom tasks. An action consists of a name and a set of callbacks. The function add_action
adds a new callback to the set of callbacks of an action.
When an action is triggered, WordPress executes all callbacks hooked to the action. The execution is sequential according to the priority of each callback.
Syntax
add_action($tag, $function, $priority, $accepted_args)
adds the function $function
to the set of callbacks of the $tag
action. $priority
is the priority of $function
within the set of callbacks. $accepted_args
is the number of arguments that $function
accepts.
$priority
and $accepted_args
are optional. By default, $priority
is 10 and $accepted_args
is 1. Lower $priority
values mean earlier execution. Functions with the same priority are executed in the order in which they were added to the action.
If $tag
is 'all'
, WordPress executes $function
for all actions.
Example
The following procedure is adaptable to any situation. For this case, suppose you need to develop a solution that sends a notification email to the website administrator each time a post is updated.
Step 1: Identify if WordPress has an action that can solve your problem.
WordPress triggers the 'post_updated'
action each time a post is updated.
Step 2: Find where the action is triggered in the codebase.
The function do_action
triggers an action in WordPress. Open the search feature of the IDE and find occurrences of the text do_action( 'post_updated'
in the codebase. You will find that this action is triggered only once and it is documented using PHPDoc comments. The call is in the file post.php.
Note that the search criterion has a whitespace after do_action(
.
/**
* Fires once an existing post has been updated.
*
* @since 3.0.0
*
* @param int $post_ID Post ID.
* @param WP_Post $post_after Post object following the update.
* @param WP_Post $post_before Post object before the update.
*/
do_action( 'post_updated', $post_ID, $post_after, $post_before);
Step 3: Develop a compatible function according to your needs or find an existing one.
The 'post_updated'
action is triggered passing three arguments: the post ID, the post object after the update, and the post object before the update. Therefore, any function hooked to this action can take up to three parameters.
We will send a custom message to the website administrator, so we need to develop a new function. Since we do not need to compare values before and after the update, the function only uses the second argument passed in the call to do_action
.
/*
* Sends an email to the website administrator notifying that a post has been updated.
*/
function ns_notify_post_updated($post_ID){
$to = get_bloginfo('admin_email');
$subject = __('Post Updated', 'ns');
$message = __('Hello Admin! The following post has been updated: ', 'ns') . get_permalink($post_ID);
wp_mail($to, $subject, $message);
}
Step 4: Hook the function to the action.
Use add_action
to add the function ns_notify_post_updated
to the set of callbacks of the 'post_updated'
action.
add_action('post_updated', 'ns_notify_post_updated', 10, 1);
Step 5: Test.
Update various posts and check the inbox of the administrative email address. Note that your server must be properly configured to send emails.
Further reading
I recommend the other tutorials in this series to learn more about actions in WordPress.
- Actions in WordPress
- How to Hook a Function to an Action in WordPress
- How to Trigger an Action in WordPress
- How to Unhook a Function From an Action in WordPress
Exercise
Develop a solution that sends a notification email to the website administrator each time an attachment is added.
Source code
The source code developed in this tutorial, including a possible answer to the exercise, is available here.
Comments