add_action( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 )

Hooks a function on to a specific action.

Contents

Description Description

Actions are the hooks that the WordPress core launches at specific points during execution, or when specific events occur. Plugins can specify that one or more of its PHP functions are executed at these points, using the Action API.

Parameters Parameters

$tag

(string) (Required) The name of the action to which the $function_to_add is hooked.

$function_to_add

(callable) (Required) The name of the function you wish to be called.

$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 value: 10

$accepted_args

(int) (Optional) The number of arguments the function accepts.

Default value: 1

Top ↑

Return Return

(true) Will always return true.

Top ↑

Source Source

File: wp-includes/plugin.php 

function add_action( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
	return add_filter( $tag, $function_to_add, $priority, $accepted_args );
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
1.2.0 Introduced.

Top ↑

More Information More Information

Top ↑

Usage Usage

add_action( $hook, $function_to_add, $priority, $accepted_args );

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:

do_action( 'save_post', $post_ID, $post, $update );

Your add_action call would look like:

add_action( 'save_post', 'wpdocs_my_save_post', 10, 3 );

And your function would be:

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

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/plugin.php: add_filter()

Hook a function or method to a specific filter action.

Top ↑

Used By Used By

Used By
Used By Description
wp-includes/ms-site.php: wp_is_site_initialized()

Checks whether a site is initialized.
wp-admin/includes/meta-boxes.php: register_and_do_post_meta_boxes()

Registers the default post meta boxes, and runs the do_meta_boxes actions.
wp-admin/includes/misc.php: WP_Privacy_Policy_Content::text_change_check()

Quick check if any privacy info has changed.
wp-includes/class-wp-roles.php: WP_Roles::get_roles_data()

Gets the available roles data.
wp-includes/widgets/class-wp-widget-text.php: WP_Widget_Text::_register_one()

Add hooks for enqueueing assets when registering all widget instances of this widget class.
wp-includes/widgets/class-wp-widget-custom-html.php: WP_Widget_Custom_HTML::_register_one()

Add hooks for enqueueing assets when registering all widget instances of this widget class.
wp-includes/widgets/class-wp-widget-media.php: WP_Widget_Media::_register_one()

Add hooks while registering all widget instances of this widget class.
wp-includes/class-wp-editor.php: _WP_Editors::enqueue_default_editor()

Enqueue all editor scripts.
wp-includes/nav-menu.php: _wp_delete_customize_changeset_dependent_auto_drafts()

Delete auto-draft posts associated with the supplied changeset.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::import_theme_starter_content()

Import theme starter content into the customized state.
wp-includes/class-wp-post-type.php: WP_Post_Type::register_meta_boxes()

Registers the post type meta box if a custom callback was specified.
wp-includes/class-wp-post-type.php: WP_Post_Type::add_hooks()

Adds the future post hook action for the post type.
wp-includes/class-wp-customize-widgets.php: WP_Customize_Widgets::selective_refresh_init()

Adds hooks for selective refresh.
wp-includes/customize/class-wp-customize-selective-refresh.php: WP_Customize_Selective_Refresh::init_preview()

Initializes the Customizer preview.
wp-includes/customize/class-wp-customize-selective-refresh.php: WP_Customize_Selective_Refresh::enqueue_preview_scripts()

Enqueues preview scripts.
wp-includes/customize/class-wp-customize-selective-refresh.php: WP_Customize_Selective_Refresh::__construct()

Plugin bootstrap for Partial Refresh functionality.
wp-includes/rest-api.php: rest_api_default_filters()

Registers the default REST API filters.
wp-includes/class-wp-customize-setting.php: WP_Customize_Setting::aggregate_multidimensional()

Set up the setting for aggregated multidimensional values.
wp-includes/admin-bar.php: wp_admin_bar_customize_menu()

Adds the “Customize” link to the Toolbar.
wp-includes/class-wp-widget-factory.php: WP_Widget_Factory::__construct()

PHP5 constructor.
wp-includes/customize/class-wp-customize-site-icon-control.php: WP_Customize_Site_Icon_Control::__construct()

Constructor.
wp-includes/customize/class-wp-customize-nav-menu-item-setting.php: WP_Customize_Nav_Menu_Item_Setting::__construct()

Constructor.
wp-includes/class-wp-customize-nav-menus.php: WP_Customize_Nav_Menus::customize_preview_init()

Add hooks for the Customizer preview.
wp-includes/class-wp-customize-nav-menus.php: WP_Customize_Nav_Menus::__construct()

Constructor.
wp-admin/includes/class-wp-site-icon.php: WP_Site_Icon::__construct()

Registers actions and filters.
wp-login.php: login_header()

Output the login page header.
wp-admin/includes/class-language-pack-upgrader.php: Language_Pack_Upgrader::bulk_upgrade()

Bulk upgrade language packs.
wp-admin/includes/class-theme-upgrader.php: Theme_Upgrader::install()

Install a theme package.
wp-admin/includes/class-theme-upgrader.php: Theme_Upgrader::upgrade()

Upgrade a theme.
wp-admin/includes/class-plugin-upgrader.php: Plugin_Upgrader::install()

Install a plugin package.
wp-admin/includes/class-plugin-upgrader.php: Plugin_Upgrader::upgrade()

Upgrade a plugin.
wp-admin/includes/class-wp-list-table.php: WP_List_Table::__construct()

Constructor.
wp-admin/includes/class-wp-theme-install-list-table.php: WP_Theme_Install_List_Table::prepare_items()
wp-admin/includes/update.php: wp_plugin_update_rows()
wp-admin/includes/update.php: wp_theme_update_rows()
wp-admin/includes/plugin.php: uninstall_plugin()

Uninstall a single plugin.
wp-admin/includes/plugin.php: add_menu_page()

Add a top-level menu page.
wp-admin/includes/plugin.php: add_submenu_page()

Add a submenu page.
wp-admin/includes/class-wp-plugin-install-list-table.php: WP_Plugin_Install_List_Table::prepare_items()
wp-admin/includes/class-wp-internal-pointers.php: WP_Internal_Pointers::enqueue_scripts()

Initializes the new feature pointers.
wp-admin/custom-header.php: Custom_Image_Header::__construct()

Constructor – Register administration header callback.
wp-admin/custom-header.php: Custom_Image_Header::init()

Set up the hooks for the Custom Header admin page.
wp-admin/custom-background.php: Custom_Background::__construct()

Constructor – Register administration header callback.
wp-admin/custom-background.php: Custom_Background::init()

Set up the hooks for the Custom Background admin page.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::customize_preview_init()

Print JavaScript settings.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::setup_theme()

Start preview and customize theme.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::__construct()

Constructor.
wp-includes/theme.php: _custom_header_background_just_in_time()

Registers the internal custom header and background routines.
wp-includes/general-template.php: add_thickbox()

Enqueues the default ThickBox js and css.
wp-includes/functions.php: wp_auth_check_load()

Load the auth check for monitoring whether the user is still logged in.
wp-includes/functions.php: wp_maybe_load_widgets()

Determines if Widgets library should be loaded.
wp-includes/widgets/class-wp-widget-recent-comments.php: WP_Widget_Recent_Comments::__construct()

Sets up a new Recent Comments widget instance.
wp-includes/class-wp-locale.php: WP_Locale::init()

Sets up the translated strings and object properties.
wp-includes/class-wp-embed.php: WP_Embed::__construct()

Constructor
wp-includes/class-wp-admin-bar.php: WP_Admin_Bar::add_menus()
wp-includes/class-wp-admin-bar.php: WP_Admin_Bar::initialize()
wp-includes/plugin.php: register_activation_hook()

Set the activation hook for a plugin.
wp-includes/plugin.php: register_deactivation_hook()

Set the deactivation hook for a plugin.
wp-includes/class-wp-customize-setting.php: WP_Customize_Setting::preview()

Add filters to supply the setting’s value when accessed.
wp-includes/media.php: wp_enqueue_media()

Enqueues all scripts, styles, settings, and templates necessary to use all media JS APIs.
wp-includes/media.php: wp_playlist_scripts()

Outputs and enqueue default scripts and styles for playlists.
wp-includes/class-wp-rewrite.php: WP_Rewrite::wp_rewrite_rules()

Retrieves the rewrite rules.
wp-includes/class-wp-rewrite.php: WP_Rewrite::flush_rules()

Removes rewrite rules and then recreate rewrite rules.
wp-includes/rewrite.php: add_feed()

Add a new feed type like /atom1/.
wp-includes/class.wp-scripts.php: WP_Scripts::__construct()

Constructor.
wp-includes/customize/class-wp-customize-header-image-control.php: WP_Customize_Header_Image_Control::prepare_control()
wp-includes/class-wp-customize-widgets.php: WP_Customize_Widgets::customize_preview_init()

Adds hooks for the Customizer preview.
wp-includes/class-wp-customize-widgets.php: WP_Customize_Widgets::__construct()

Initial loader.
wp-includes/class-wp-customize-widgets.php: WP_Customize_Widgets::schedule_customize_register()

Ensures widgets are available for all types of previews.
wp-includes/comment.php: wp_set_comment_status()

Sets the status of a comment.
wp-includes/class-wp-editor.php: _WP_Editors::editor_settings()
wp-includes/media-template.php: wp_print_media_templates()

Prints the templates used in the media manager.
Show 67 more used by Hide more used by

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 31You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Using with a Class
    To use add_action() when your plugin or theme is built using classes, you need to use the array callable syntax. You would pass the function to add_action() as an array, with $this as the first element, then the name of the class method, like so:

    /**
 * Class WP_Docs_Class.
 */
class WP_Docs_Class {

	/**
	 * Constructor
	 */
	public function __construct() {
		add_action( 'save_post', array( $this, 'wpdocs_save_posts' ) );
	}

	/**
	 * Handle saving post data.
	 */
	public function wpdocs_save_posts() {
		// do stuff here...
	}
}

$wpdocsclass = new WP_Docs_Class();

    Expand full source codeCollapse full source code

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 18You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Using with static functions in a class
    If the class is called staticly the approach has to be like below as $this is not available. This also works if class is extended. Use the following:

    /**
 * Class WP_Docs_Static_Class.
 */
class WP_Docs_Static_Class {

	/**
	 * Initializer for setting up action handler
	 */
	public static function init() {
		add_action( 'save_post', array( get_called_class(), 'wpdocs_save_posts' ) );
	}

	/**
	 * Handler for saving post data.
	 */
	public static function wpdocs_save_posts() {
		// do stuff here...
	}
}

WP_Docs_Static_Class::init();

    Expand full source codeCollapse full source code

  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note
    Contributed by Codex —

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

    /**
 * Send email to my friends.
 *
 * @param int $post_id Post ID.
 * @return int Post ID.
 */
function wpdocs_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', 'wpdocs_email_friends' );

    Expand full source codeCollapse full source code

  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Accepted Arguments
    A hooked function can optionally accept arguments from the action call, 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.

    /**
 * Warn about comment not found
 *
 * @param int $comment_id Comment ID.
 */
function echo_comment_id( $comment_id ) {
	printf( 'Comment ID %s could not be found', esc_html( $comment_id ) );
}
add_action( 'comment_id_not_found', 'echo_comment_id', 10, 1 );
  6. Skip to note 6 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by lucasbustamante —

    Passing parameters while using in a Class
    To pass parameters to your method in a Class while calling it with add_action, you can do as following:

    
public function __construct() {
    // Actions
    add_action('init', array($this, 'call_somefunction'));
}

/**
 *    Intermediate function to call add_action with parameters
 */
public function call_somefunction() {
    $this->somefunction('Hello World');
}

/**
 *    Actual function that does something
 */
public function somefunction($text) {
    echo $text;
}

    Expand full source codeCollapse full source code

You must log in before being able to contribute a note or feedback.