WordPress.org

Function Reference/add action

Languages: English • 日本語 • 中文(简体) • 한국어 • (Add your language)

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 you wish to hook onto. (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.

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) How important your function is. Alter this to make your function be called before or after other functions. The default is 10, so (for example) setting it to 5 would make it run earlier and setting it to 12 would make it run later.

Default: 10

$accepted_args

(int) (optional) How many arguments your function takes. 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

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');

Take Arguments

The hooked function takes one argument from the action. Specifically, the 'echo_comment_id' function, takes the argument $comment_ID. It then echos the value of the received argument.

function echo_comment_id( $comment_ID ) 
{
   echo "I just received $comment_ID";
}
add_action( 'comment_id_not_found', 'echo_comment_id', 10, 1 );

You can also pass the callback parameter as a anonymous function, for example: <?php add_action('wp_head', function() { echo 'something';}) ?>

Important note: It's not possible to remove an anonymous function using 'remove_action' (needs a function name as second argument).

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, 2 ); ?>

And your function would be:

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

Change Log

Since: 1.2.0

Source File

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

WordPress.org

Codex