Actions in WordPress

Problem

Most of the time our code calls code in the WordPress Core, but in other situations we need that the WordPress Core be able to call our code.

Example: Send a notification email to all subscribers each time a post is published.

Actions

WordPress actions make possible the inversion of control described above. An action consists of:

• A name, also known as “tag” or “action hook”
• A set of callbacks

The function add_action adds a new callback to the set of callbacks of an action. This process is known as “hooking”. The function remove_action does the opposite, it removes a callback from the set of callbacks.

The function do_action triggers an action. This means that WordPress executes all callbacks hooked to the action. The execution is sequential according to the priority of each callback.

Available actions

The list of actions triggered by the WordPress Core is large. Plugins and themes can also create their own actions. Some actions are:

• 'post_updated' —triggered once a post is updated
• 'trashed_post' —triggered after a post is sent to the Trash
• 'delete_attachment' —triggered before an attachment is deleted

To get a complete list, search the codebase for calls to the function do_action. Each call triggers an action and the action is documented in detail using PHPDoc comments. Below is the code that triggers the 'post_updated' action. This code is placed in the file post.php of the WordPress Core.

/**
 * 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);

Example

The following code defines the function ns_notify_post_published and hooks it to the 'transition_post_status' action. This action is triggered each time a post is transitioned from one status to another status. The result is that an email is sent to a list of addresses each time a post is published.

/*
 * Sends an email notifying that a post has been published.
 */
function ns_notify_post_published($new_status, $old_status, $post){
    
    $is_post_published = ($old_status != 'publish') && ($new_status == 'publish');
    if($is_post_published){
        $to = array('address1@example.com', 'address2@example.com', 'address3@example.com');
        $subject = __('Hello!', 'ns');;
        $message = __('I just published this on my website: ', 'ns') . get_permalink($post);
        wp_mail($to, $subject, $message);
    }
}
add_action('transition_post_status', 'ns_notify_post_published', 10, 3);

Actions vs filters

Actions and filters have similarities. Both concepts make possible the injection of code and the writing of extensible code in WordPress. Their API is very similar. There are just slight variations in the naming of functions.

The difference is in purpose. Actions allow us to do something when the action is triggered, whereas filters allow us to replace a value when the filter is triggered.

Source code

The source code developed in this tutorial is available here.