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.
Some – where is the add_action stored, when is it run and what program calls it?
Hi Terry,
Thank you for your question regarding add_action. The add_action function is stored in the wp-includes/plugin.php and is used by various plugins when a callback function needs to be added to an action hook. WordPress Core launches action hooks at specific times during execution.
Best Regards,
Alyssa K.
Ok, I’ll rephrase my question. There are, potentially, dozens of add_action functions in WordPress. Some are in reference to the core, some created by template and plugins. These all have to be executed before WordPress gets very far in its initial execution so they can be ready to run when the triggering do_action is run.
So when are the add_action functions run, where is the info stored and what program does it?
Hi Terry, we’ve talked it over and we’re still not sure what exactly you’re trying to figure out.
As Alyssa said, the code necessary to run an
add_actionis stored inwp-includes/plugin.php, while the individual uses ofadd_actionwill be in a variety of plugin files, each tied to their specific purpose. Some will run when the page loads and parses the PHP file, while others will run when a user action specifically utilizes a plugin.The program in this case is the browser, running code by way of the WordPress framework — along with the Apache server software depending on how meta-analytical you want to get about it.
Are you trying to optimize a particular aspect of a plugin or page, or perform some other type of modification to your site? Please describe the scenario and we’ll do our best to assist. If you’re just asking out of general curiosity, though, the official WordPress codex is a great resource for more in depth guides on specific aspects of WordPress, as are WordPress IRC channels and other methods of directly contacting the developers. Hope that helps!
Hi Terry, I went and consulted with some colleagues regarding the WordPress page loading process and have some information that may prove helpful to what you’re working on.
One thing our article above doesn’t mention is
do_action.add_actionanddo_actionwork together to get actions done.Another thing to note is that there are many different actions, both on the front end and in the admin pages. They are also ran in a specific order. I recommend checking out this page as a reference on WordPress order of precedence.
The actions are triggered by
do_action, and thosedo_actions are usually placed in the code near the action is actually happening.For example, after a user is logged out, the
wp_logoutaction is triggered, as you an see here in the WordPress code.If you wanted to add an action to that event, your plugin would simply have to add it anytime before that
do_actionis called.When you’re adding an action, you’re simply telling WordPress to run a function. There’s not really data be stored, WordPress can pass data to the function. In the example above, WordPress passes the
$user_idto functions attached with theadd_action.So, first the plugin adds an action:
add_action( 'wp_logout', function( $user_id ) {error_log( 'The following user has logged out: ' . $user_id );
} );
And then triggers the action:
do_action( 'wp_logout', $user_id );I hope this helps!