The add_action WordPress function

The add_action function is arguably the most used function in WordPress. Simply put, it allows you to run a function when a particular hook occurs. In this article, we will introduce you to the add_action function and teach you how to use it in your first WordPress plugin.

For example, if you wanted to add estimated reading time to posts this is a good way to incorporate that code into your site without editing the theme.

Usage

<?php add_action( $hook, $function_to_add, $priority, $accepted_args ); ?>

Parameters

$hook

This required parameter determines the action that will be hooked into. Whenever this action is run, the associated function defined in add_action will also run. This can be the name of any action that is run, including those located within a theme or plugin.

$function_to_add

This is a required parameter which allows you to define the function that will be run at the time that the previously defined action occurs. Simply placing the name of the desired function here will allow it to run each time the action in the $hook parameter is called.

$priority

This optional parameter allows you to define the order in which functions are executed. If you have multiple functions that are occurring on a particular action hook, you would adjust this parameter to determine the order in which they are exectuted. Lower numbers are executed sooner that higher numbers and functions with the same priority will be executed in the order in which they were added.

$accepted_args

It is possible to pass additional arguments directly to the hook that you are calling the additional function on. The $accepted_args parameter will allow you to define the number of parameters accepted from the action hook to the function being called in the add_action function.

Code Examples

<?php
function detect_published_post ( $new_status = NULL, $old_status = NULL, $post_ID = NULL ) {
if ( 'publish' == $new_status && 'publish' != $old_status ) {
echo 'This new post has been published: ' . $post_ID->post_title;
}
}

add_action( 'transition_post_status', 'detect_published_post', 10, 3 );
?>

In this example, we are calling the detect_published_post function when the transition_post_status hook is called. We have defined the priority as 10, and the accepted arguments as 3 as the transition_post_status hook provides information on the new status, the old status, and the post ID. As we want to use those arguments in our code, we have also defined them within the function. From there, we can do anything we want with that information quite easily and make changes as soon as a post status has changed.