How to Hook 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.

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.

/**
 * 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.

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.