Codex

Plugin API/Action Reference

This article is a (hopefully complete) list of the action hooks available for use in plugin development in Version 2.1 and above of WordPress. For more information:

Note: If you want to add to or clarify this documentation, please follow the style of the existing entries. Describe when the action runs, and if the action function takes arguments, describe the arguments.

Contents

Post, Page, Attachment, and Category Actions

add_attachment
Runs when an attached file is first added to the database. Action function arguments: attachment ID.
add_category
Same as create_category.
create_category
Runs when a new category is created. Action function arguments: category ID.
delete_attachment
Runs just after an attached file is deleted from the database. Action function arguments: attachment ID.
delete_category
Runs just after a category is deleted from the database and its corresponding links/posts are updated to remove the category. Action function arguments: category ID.
delete_post
Runs when a post or page is about to be deleted. Action function arguments: post or page ID.
edit_attachment
Runs when an attached file is edited/updated to the database. Action function arguments: attachment ID.
edit_category
Runs when a category is updated/edited, including when a post or blogroll link is added/deleted or its categories are updated (which causes the count for the category to update). Action function arguments: category ID.
edit_post 
Runs when a post or page is updated/edited, including when a comment is added or updated (which causes the comment count for the post to update). Action function arguments: post or page ID.
private_to_published 
Runs when a post is changed from private to published status. Action function arguments: post ID.
publish_page 
Runs when a page is published, or if it is edited and its status is "published". Action function arguments: page ID. (WARNING: this hook seems to never fire on v2.3 and higher. The 'transition_post_status' hook does work though)
publish_phone 
Runs just after a post is added via email. Action function argument: post ID.
publish_post 
Runs when a post is published, or if it is edited and its status is "published". Action function arguments: post ID.
save_post 
Runs whenever a post or page is created or updated, which could be from an import, post/page edit form, xmlrpc, or post by email. Action function arguments: post ID.
wp_insert_post 
Same as save_post, runs just afterwards.
xmlrpc_publish_post
Runs when a post is published via XMLRPC request, or if it is edited via XMLRPC and its status is "published". Action function arguments: post ID.

Comment, Ping, and Trackback Actions

comment_closed 
Runs when the post is marked as not allowing comments while trying to display comment entry form. Action function argument: post ID.
comment_id_not_found 
Runs when the post ID is not found while trying to display comments or comment entry form. Action function argument: post ID.
comment_flood_trigger
Runs when a comment flood is detected, just before wp_die is called to stop the comment from being accepted. Action function arguments: time of previous comment, time of current comment.
comment_on_draft
Runs when the post is a draft while trying to display a comment entry form or comments. Action function argument: post ID.
comment_post
Runs just after a comment is saved in the database. Action function arguments: comment ID, approval status ("spam", or 0/1 for disapproved/approved).
edit_comment 
Runs after a comment is updated/edited in the database. Action function arguments: comment ID.
delete_comment 
Runs just before a comment is deleted. Action function arguments: comment ID.
pingback_post
Runs when a ping is added to a post. Action function argument: comment ID.
pre_ping
Runs before a ping is fully processed. Action function arguments: array of the post links to be processed, and the "pung" setting for the post.
trackback_post
Runs when a trackback is added to a post. Action function argument: comment ID.
wp_blacklist_check
Runs to check whether a comment should be blacklisted. Action function arguments: author name, author email, author URL, comment text, author IP address, author's user agent (browser). Your function can execute a wp_die to reject the comment, or perhaps modify one of the input arguments so that it will contain one of the blacklist keywords set in the WordPress options.
wp_set_comment_status 
Runs when the status of a comment changes. Action function arguments: comment ID, status string indicating the new status ("delete", "approve", "spam", "hold").

Blogroll Actions

add_link
Runs when a new blogroll link is first added to the database. Action function arguments: link ID.
delete_link
Runs when a blogroll link is deleted. Action function arguments: link ID.
edit_link
Runs when a blogroll link is edited. Action function arguments: link ID.

Feed Actions

atom_entry
Runs just after the entry information has been printed (but before closing the entry tag) for each blog entry in an atom feed.
atom_head
Runs just after the blog information has been printed in an atom feed, just before the first entry.
atom_ns
Runs inside the root XML element for an atom feed (to add namespaces).
commentrss2_item
Runs just after a single comment's information has been printed in a comment feed (but before closing the item tag). Action function arguments: comment ID, post ID.
do_feed_feed
Runs when a feed is generated, where feed is the type of feed (rss2, atom, rdf, etc.). Use priority less than 10 to run before printing the feed. Action function argument: true (the feed is for comments) or false (it is for posts).
rdf_header
Runs just after the blog information has been printed in an RDF feed, just before the first entry.
rdf_item
Runs just after the entry information has been printed (but before closing the item tag) for each blog entry in an RDF feed.
rdf_ns
Runs inside the root XML element in an RDF feed (to add namespaces).
rss_head
Runs just after the blog information has been printed in an RSS feed, just before the first entry.
rss_item
Runs just after the entry information has been printed (but before closing the item tag) for each blog entry in an RSS feed.
rss2_head
Runs just after the blog information has been printed in an RSS 2 feed, just before the first entry.
rss2_item
Runs just after the entry information has been printed (but before closing the item tag) for each blog entry in an RSS 2 feed.
rss2_ns
Runs inside the root XML element in an RSS 2 feed (to add namespaces).

Template Actions

comment_form 
Runs in standard themes to insert the comment form. Action function argument: post ID.
do_robots
Runs when the template file chooser determines that it is a robots.txt request.
do_robotstxt
Runs in the do_robots function before it prints out the Disallow lists for the robots.txt file.
get_footer
Runs when the template calls the get_footer function, just before the footer.php template file is loaded.
get_header
Runs when the template calls the get_header function, just before the header.php template file is loaded.
switch_theme 
Runs when the blog's theme is changed. Action function argument: name of the new theme.
template_redirect
Runs before the determination of the template file to be used to display the requested page, so that a plugin can override the template file choice. Example (pedagogical, not useful): Redirect all requests to the all.php template file in the current themes' directory.
function all_on_one () {
	include(TEMPLATEPATH . '/all.php');
	exit;
}

add_action('template_redirect', 'all_on_one');
wp_footer 
Runs when the template calls the wp_footer function, generally near the bottom of the blog page.
wp_head 
Runs when the template calls the wp_head function. This hook is generally placed near the top of a page template between <head> and </head>. This hook does not take any parameters.
wp_meta 
Runs when the sidebar.php template file calls the wp_meta function, to allow the plugin to insert content into the sidebar.
wp_print_scripts
Runs just before WordPress prints registered JavaScript scripts into the page header.

Administrative Actions

activate_(plugin file name)
Runs when the plugin is first activated. See example in Creating Tables with Plugins.
activity_box_end
Runs at the end of the activity box on the admin Dashboard screen.
add_category_form_pre
Runs before the add category form is put on the screen in the admin menus.
admin_head 
Runs in the HTML <head> section of the admin panel.
admin_head-(page_hook) or admin_head-(plugin_page)
Runs in the HTML <head> section of the admin panel of a plugin-generated page.
admin_footer
Runs at the end of the admin panel inside the body tag.
admin_print_scripts
Runs in the HTML header so a plugin can add JavaScript scripts to all admin pages.
admin_print_scripts-(page_hook) or admin_print_scripts-(plugin_page)
Runs to print JavaScript scripts in the HTML head section of a specific plugin-generated admin page. The (page_hook) is returned when using any of the functions that add plugin menu items to the admin menu: add_management_page(), add_options_page(), etc. Example:
function myplugin_menu() {
  if ( function_exists('add_management_page') ) {
    $page = add_management_page( 'myplugin', 'myplugin', 9, __FILE__, 'myplugin_admin_page' );
    add_action( "admin_print_scripts-$page", 'myplugin_admin_head' );
  }
} 
check_passwords
Runs to validate the double-entry of password when creating a new user. Action function arguments: array of login name, first password, second password.
dbx_page_advanced
Runs at the bottom of the "advanced" section on the page editing screen in the admin menus.
dbx_page_sidebar
Runs at the bottom of the sidebar on the page editing screen in the admin menus.
dbx_post_advanced
Runs at the bottom of the "advanced" section on the post editing screen in the admin menus.
dbx_post_sidebar
Runs at the bottom of the sidebar on the post editing screen in the admin menus.
deactivate_(plugin file name)
Runs when a plugin is deactivated.
delete_user
Runs when a user is deleted. Action function arguments: user ID.
edit_category_form
Runs after the add/edit category form is put on the screen (but before the end of the HTML form tag).
edit_category_form_pre
Runs before the edit category form is put on the screen in the admin menus.
edit_form_advanced
Runs just before the "advanced" section of the post editing form in the admin menus.
edit_page_form
Runs just before the "advanced" section of the page editing form in the admin menus.
edit_user_profile
Runs near the end of the user profile editing screen in the admin menus.
load-(page)
Runs when an administration menu page is loaded. This action is not usually added directly -- see Adding Administration Menus for more details of how to add admin menus. If you do want to use it directly, the return value from add_options_page and similar functions gives you the (page) part of the action name.
login_form
Runs just before the end of the login form.
login_head
Runs just before the end of the HTML head section of the login page.
lost_password
Runs before the "retrieve your password by email" form is printed on the login screen.
lostpassword_form
Runs at the end of the form used to retrieve a user's password by email, to allow a plugin to supply extra fields.
lostpassword_post
runs when the user has requested an email message to retrieve their password, to allow a plugin to modify the PHP $_POST variable before processing.
manage_link_custom_column
Runs when there is an unknown column name for the blogroll managing admin screen. Action function arguments: column name, link ID. See also filter manage_link_columns in the Plugin API/Filter Reference, which adds custom columns.
manage_posts_custom_column
Runs when there is an unknown column name for the managing posts admin screen. Action function arguments: column name, post ID. See also filter manage_posts_columns in the Plugin API/Filter Reference, which adds custom columns. (see Scompt's tutorial for examples and use.)
manage_pages_custom_column
Runs when there is an unknown column name for the managing pages admin screen. Action function arguments: column name, page ID. See also filter manage_pages_columns in the Plugin API/Filter Reference, which adds custom columns.
password_reset
Runs before the user's password is reset to a random new password.
personal_options_update
Runs when a user updates personal options from the admin screen.
plugins_loaded
Runs after all plugins have been loaded.
profile_personal_options
Runs at the end of the Personal Options section of the user profile editing screen.
profile_update
Runs when a user's profile is updated. Action function argument: user ID.
register_form
Runs just before the end of the new user registration form.
register_post
Runs before a new user registration request is processed.
restrict_manage_posts
Runs before the list of posts to edit is put on the screen in the admin menus.
retrieve_password
Runs when a user's password is retrieved, to send them a reminder email. Action function argument: login name.
set_current_user
Runs after the user has been changed by the default wp_set_current_user function. Note that wp_set_current_user is also a "pluggable" function, meaning that plugins can override it; see Plugin API).
show_user_profile
Runs near the end of the user profile editing screen.
simple_edit_form
Runs at the end of the "simple" post editing form in the admin menus (by default the simple form is used only for bookmarklets -- it doesn't have the "advanced" sections).
update_option_(option_name)
Runs after a WordPress option has been update by the update_option function. Action function arguments: old option value, new option value. You must add an action for the specific options that you want to respond to, such as update_option_foo to respond when option "foo" has been updated.
upload_files_(tab) 
Runs to print a screen on the upload files admin screen; "tab" is the name of the custom action tab. Define custom tabs using the wp_upload_tabs filter (see Plugin API/Filter Reference).
user_register
Runs when a user's profile is first created. Action function argument: user ID.
wp_ajax_(action)
Runs to do an unknown type of AJAX action in the administrative menus.
wp_authenticate
Runs to authenticate a user when they log in. Action function arguments: array with user name and password.
wp_login
Runs when a user logs in.
wp_logout
Runs when a user logs out.

Advanced Actions

This section contains actions related to the queries WordPress uses to figure out what posts to display, the WordPress loop, activating plugins, and other fundamental-level WordPress code.

admin_menu
Runs after the basic admin panel menu structure is in place.
admin_notices
Runs after the admin menu is printed to the screen.
blog_privacy_selector
Runs after the default blog privacy options are printed on the screen.
check_admin_referer
Runs in the default check_admin_referrer function after the nonce has been checked for security purposes, to allow a plugin to force WordPress to die for extra security reasons. Note that check_admin_referrer is also a "pluggable" function, meaning that plugins can override it; see Plugin API).
check_ajax_referer
Runs in the default check_ajax_referer function (which is called when an AJAX request goes to the wp-admin/admin-ajax.php script) after the user's login and password have been successfully validated from cookies, to allow a plugin to force WordPress to die for extra security reasons. Note that check_ajax_referer is also a "pluggable" function, meaning that plugins can override it; see Plugin API).
generate_rewrite_rules 
Runs after the rewrite rules are generated. Action function arguments: the WP_Rewrite class variables as a list. Note that it is easier to use the rewrite_rules_array filter instead of this action, to modify the rewrite rules.
init
Runs after WordPress has finished loading but before any headers are sent. Useful for intercepting $_GET or $_POST triggers.
loop_end
Runs after the last post of the WordPress loop is processed.
loop_start
Runs before the first post of the WordPress loop is processed.
parse_query
Runs at the end of query parsing. Action function arguments: contents of the $wp_query object as a list.
parse_request
Runs after the query request is parsed inside the main WordPress function wp. Action function argument: an array with a reference to the global $wp object.
pre_get_posts
Runs before the query in the get_posts function. Action function argument: contents of the $wp_query object, as a list.
sanitize_comment_cookies
Runs after cookies have been read from the HTTP request.
send_headers
Runs after the basic HTTP headers are sent inside the main WordPress function wp. Action function argument: an array with a reference to the global $wp object.
shutdown
Runs when the page output is complete.
wp 
Executes after the query has been parsed and post(s) loaded, but before any template execution, inside the main WordPress function wp. Useful if you need to have access to post data but can't use templates for output. Action function argument: an array with a reference to the global $wp object.

Further Reading

  • Writing a Plugin - description of how to write a plugin
  • Plugin API - article on how to use filters and actions
  • Plugin API/Filter Reference - reference list for filter hooks
  • Plugin Resources - comprehensive list of plugin-related resources
  • Skippy's list of actions and filters
  • WordPress Hooks, a work in progress directory of all of WordPress’ hooks.
  • WordPress Hooks Database, a database of all WordPress' hooks, showing which version they come from, and linking to the source code spots that use them
  • Angsuman's list, a comprehensive listing of WordPress action hooks with documentation and source code location information. It contains all documented and undocumented action hooks in WordPress 2.0.