WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Difference between revisions of "Function Reference/add action"

m (Document "all" tag for add_action)
(Using an anonymous function is bad practice and we shouldn't encourage it)
Line 52: Line 52:
 
add_action( 'comment_id_not_found', 'echo_comment_id', 10, 1 );
 
add_action( 'comment_id_not_found', 'echo_comment_id', 10, 1 );
 
</pre>
 
</pre>
 
You can also pass the callback parameter as a anonymous function, for example:
 
%%% <?php add_action('wp_head', function() { echo 'something';}) ?> %%%
 
 
<!-- WP now doesn't support PHP 4 compatility anymore.
 
<em>Note:</em> For PHP 4 compatibility, use create_function() for anonymous functions.
 
-->
 
<em><strong>Important note:</strong> It's not possible to remove an anonymous function using [[Function_Reference/remove_action|remove_action()]], which requires a function name as its second argument.</em>
 
   
 
== Notes ==
 
== Notes ==

Revision as of 18:04, 18 December 2012

Description

Hooks a function on to a specific action.

See Plugin API/Action Reference for a list of hooks for action. Actions are (usually) triggered when the WordPress core calls do_action().

Usage

 <?php add_action$tag$function_to_add$priority$accepted_args ); ?> 

Parameters

$tag
(string) (required) The name of the action to which $function_to_add is hooked. (See Plugin API/Action Reference for a list of action hooks). Can also be the name of an action inside a theme or plugin file, or the special tag "all", in which case the function will be called for all hooks.
Default: None
$function_to_add
(callback) (required) The name of the function you wish to be called. Note: Only string-formatted syntaxes listed in the PHP documentation for the 'callback' type are valid.
Default: None
$priority
(int) (optional) Used to specify the order in which the functions associated with a particular action are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.
Default: 10
$accepted_args
(int) (optional) The number of arguments the function accepts. In WordPress 1.5.1+, hooked functions can take extra arguments that are set when the matching do_action() or apply_filters() call is run. For example, the action comment_id_not_found will pass any functions that hook onto it the ID of the requested comment.
Default: 1

Return Values

(boolean) 
Always True.

Examples

Simple Hook

To email some friends whenever an entry is posted on your blog:

function email_friends( $post_ID )  
{
   $friends = 'bob@example.org, susie@example.org';
   wp_mail( $friends, "sally's blog updated", 'I just put something on my blog: http://blog.example.com' );

   return $post_ID;
}
add_action( 'publish_post', 'email_friends' );

Accepted Arguments

A hooked function can optionally accept arguments from the calling action, if any are set to be passed. In this simplistic example, the echo_comment_id function takes the $comment_id argument, which is automatically passed to when the do_action() call using the comment_id_not_found filter hook is run.

function echo_comment_id( $comment_id ) 
{
   echo 'Comment ID ' . $comment_id . ' could not be found';
}
add_action( 'comment_id_not_found', 'echo_comment_id', 10, 1 );

Notes

To find out the number and name of arguments for an action, simply search the code base for the matching do_action() call. For example, if you are hooking into 'save_post', you would find it in post.php:  <?php do_action'save_post'$post_ID$post ); ?> 

Your add_action call would look like:  <?php add_action'save_post''my_save_post'10); ?> 

And your function would be:

function my_save_post( $post_ID, $post )
{
   // do stuff here
}

Using add_action with a class

To use the add_action hook when your plugin or theme is built up using classes, add $this to your add_action call together with the function name within that class, like so:

class MyPluginClass
{
    public function __construct()
    {
         //add your actions to the constructor!
         add_action( 'save_post', array( $this, 'myplugin_save_posts' ) );
    }
    
    public function myplugin_save_posts()
    {
         //do stuff here...
    }
}

Change Log

Since: 1.2.0

Source File

add_action() is located in wp-includes/plugin.php.

Related

Actions: has_action(), add_action(), do_action(), do_action_ref_array(), did_action(), remove_action(), remove_all_actions()

See also index of Function Reference and index of Template Tags.
This article is marked as in need of editing. You can help Codex by editing it.