check_ajax_referer()

💡 云策文档标注

概述

check_ajax_referer() 函数用于验证 Ajax 请求中的 nonce，以防止处理来自博客外部的请求。它检查 $_REQUEST 中的 nonce 值，并根据验证结果返回状态码或停止脚本执行。

关键要点

参数：$action（可选，默认 -1）指定 nonce 动作；$query_arg（可选，默认 false）指定 $_REQUEST 中 nonce 的键；$stop（可选，默认 true）控制验证失败时是否停止执行。
返回值：1 表示 nonce 有效且在 0-12 小时内生成；2 表示有效且在 12-24 小时内生成；false 表示无效。
注意事项：nonce 不应用于身份验证、授权或访问控制，应结合 current_user_can() 使用；函数可通过插件替换；默认查找顺序为 '_ajax_nonce' 和 '_wpnonce'。
Hook：do_action('check_ajax_referer', $action, $result) 在验证后触发。

代码示例

/**
 * Check the referrer for the AJAX call.
 */
function wpdocs_action_function() {
    check_ajax_referer( 'wpdocs-special-string', 'security' );
    echo sanitize_text_field( $_POST['wpdocs_string'] );
    die;
}
add_action( 'wp_ajax_wpdocs_action', 'wpdocs_action_function' );

📄 原文内容

Verifies the Ajax request to prevent processing requests external of the blog.

Parameters

$actionint|stringoptional: Action nonce.

Default:-1
$query_argfalse|stringoptional: Key to check for the nonce in $_REQUEST (since 2.5). If false, $_REQUEST values will be evaluated for '_ajax_nonce', and '_wpnonce' (in that order).

Default:false
$stopbooloptional: Whether to stop early when the nonce cannot be verified.

Default:true

Return

int|false 1 if the nonce is valid and generated between 0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
False if the nonce is invalid.

More Information

Nonces should never be relied on for authentication, authorization, or access control. Protect your functions using current_user_can() and always assume that nonces can be compromised.

This function can be replaced via plugins. If plugins do not redefine these functions, then this will be used instead.

If $query_arg is not specified (i.e. defaults to false), then the function will look for the nonce in '_ajax_nonce'. If that is not set, then it will assume that the nonce is in '_wpnonce', regardless of whether that query arg actually exists.

If $die is set to true, execution of the script will be stopped if the nonce cannot be verified, and the output will be '-1'.

Source

function check_ajax_referer( $action = -1, $query_arg = false, $stop = true ) {
	if ( -1 === $action ) {
		_doing_it_wrong( __FUNCTION__, __( 'You should specify an action to be verified by using the first parameter.' ), '4.7.0' );
	}

	$nonce = '';

	if ( $query_arg && isset( $_REQUEST[ $query_arg ] ) ) {
		$nonce = $_REQUEST[ $query_arg ];
	} elseif ( isset( $_REQUEST['_ajax_nonce'] ) ) {
		$nonce = $_REQUEST['_ajax_nonce'];
	} elseif ( isset( $_REQUEST['_wpnonce'] ) ) {
		$nonce = $_REQUEST['_wpnonce'];
	}

	$result = wp_verify_nonce( $nonce, $action );

	/**
	 * Fires once the Ajax request has been validated or not.
	 *
	 * @since 2.1.0
	 *
	 * @param string    $action The Ajax nonce action.
	 * @param false|int $result False if the nonce is invalid, 1 if the nonce is valid and generated between
	 *                          0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
	 */
	do_action( 'check_ajax_referer', $action, $result );

	if ( $stop && false === $result ) {
		if ( wp_doing_ajax() ) {
			wp_die( -1, 403 );
		} else {
			die( '-1' );
		}
	}

	return $result;
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘check_ajax_referer’, string $action, false|int $result ): Fires once the Ajax request has been validated or not.

Uses	Description
wp_doing_ajax()`wp-includes/load.php`	Determines whether the current request is a WordPress Ajax request.
wp_verify_nonce()`wp-includes/pluggable.php`	Verifies that a correct security nonce was used with time limit.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
_doing_it_wrong()`wp-includes/functions.php`	Marks something as being incorrectly called.
wp_die()`wp-includes/functions.php`	Kills WordPress execution and displays HTML page with an error message.
do_action()`wp-includes/plugin.php`	Calls the callback functions that have been added to an action hook.

Show 4 more Show less

Used by	Description
WP_Plugin_Dependencies::check_plugin_dependencies_during_ajax()`wp-includes/class-wp-plugin-dependencies.php`	Checks plugin dependencies after a plugin is installed via AJAX.
wp_ajax_activate_plugin()`wp-admin/includes/ajax-actions.php`	Handles activating a plugin via AJAX.
wp_ajax_send_password_reset()`wp-admin/includes/ajax-actions.php`	Handles sending a password reset link via AJAX.
wp_ajax_toggle_auto_updates()`wp-admin/includes/ajax-actions.php`	Handles enabling or disable plugin and theme auto-updates via AJAX.
wp_ajax_media_create_image_subsizes()`wp-admin/includes/ajax-actions.php`	Handles creating missing image sub-sizes for just uploaded images via AJAX.
wp_ajax_health_check_get_sizes()`wp-admin/includes/ajax-actions.php`	Handles site health check to get directories and database sizes via AJAX.
wp_ajax_health_check_dotorg_communication()`wp-admin/includes/ajax-actions.php`	Handles site health checks on server communication via AJAX.
wp_ajax_health_check_background_updates()`wp-admin/includes/ajax-actions.php`	Handles site health checks on background updates via AJAX.
wp_ajax_health_check_loopback_requests()`wp-admin/includes/ajax-actions.php`	Handles site health checks on loopback requests via AJAX.
wp_ajax_health_check_site_status_result()`wp-admin/includes/ajax-actions.php`	Handles site health check to update the result status via AJAX.
wp_ajax_wp_privacy_export_personal_data()`wp-admin/includes/ajax-actions.php`	Handles exporting a user’s personal data via AJAX.
wp_ajax_wp_privacy_erase_personal_data()`wp-admin/includes/ajax-actions.php`	Handles erasing personal data via AJAX.
WP_Customize_Manager::handle_load_themes_request()`wp-includes/class-wp-customize-manager.php`	Loads themes into the theme browsing/installation UI.
WP_Customize_Manager::handle_override_changeset_lock_request()`wp-includes/class-wp-customize-manager.php`	Removes changeset lock when take over request is sent via Ajax.
WP_Customize_Manager::handle_dismiss_autosave_or_lock_request()`wp-includes/class-wp-customize-manager.php`	Deletes a given auto-draft changeset or the autosave revision for a given changeset or delete changeset lock.
WP_Customize_Manager::handle_changeset_trash_request()`wp-includes/class-wp-customize-manager.php`	Handles request to trash a changeset.
wp_ajax_get_community_events()`wp-admin/includes/ajax-actions.php`	Handles Ajax requests for community events
WP_Customize_Nav_Menus::ajax_insert_auto_draft_post()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for adding a new auto-draft post.
wp_ajax_search_install_plugins()`wp-admin/includes/ajax-actions.php`	Handles searching plugins to install via AJAX.
wp_ajax_delete_plugin()`wp-admin/includes/ajax-actions.php`	Handles deleting a plugin via AJAX.
wp_ajax_search_plugins()`wp-admin/includes/ajax-actions.php`	Handles searching plugins via AJAX.
wp_ajax_install_theme()`wp-admin/includes/ajax-actions.php`	Handles installing a theme via AJAX.
wp_ajax_update_theme()`wp-admin/includes/ajax-actions.php`	Handles updating a theme via AJAX.
wp_ajax_delete_theme()`wp-admin/includes/ajax-actions.php`	Handles deleting a theme via AJAX.
wp_ajax_install_plugin()`wp-admin/includes/ajax-actions.php`	Handles installing a plugin via AJAX.
wp_ajax_get_post_thumbnail_html()`wp-admin/includes/ajax-actions.php`	Handles retrieving HTML for the featured image via AJAX.
wp_ajax_save_wporg_username()`wp-admin/includes/ajax-actions.php`	Handles saving the user’s WordPress.org username via AJAX.
wp_ajax_delete_inactive_widgets()`wp-admin/includes/ajax-actions.php`	Handles removing inactive widgets via AJAX.
WP_Customize_Nav_Menus::ajax_load_available_items()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for loading available menu items.
WP_Customize_Nav_Menus::ajax_search_available_items()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for searching available menu items.
wp_ajax_crop_image()`wp-admin/includes/ajax-actions.php`	Handles cropping an image via AJAX.
wp_ajax_update_plugin()`wp-admin/includes/ajax-actions.php`	Handles updating a plugin via AJAX.
Custom_Background::ajax_background_add()`wp-admin/includes/class-custom-background.php`	Handles Ajax request for adding custom background context to an attachment.
wp_ajax_set_attachment_thumbnail()`wp-admin/includes/ajax-actions.php`	Handles setting the featured image for an attachment via AJAX.
wp_ajax_save_attachment_order()`wp-admin/includes/ajax-actions.php`	Handles saving the attachment order via AJAX.
wp_ajax_send_attachment_to_editor()`wp-admin/includes/ajax-actions.php`	Handles sending an attachment to the editor via AJAX.
wp_ajax_send_link_to_editor()`wp-admin/includes/ajax-actions.php`	Handles sending a link to the editor via AJAX.
wp_ajax_save_user_color_scheme()`wp-admin/includes/ajax-actions.php`	Handles auto-saving the selected color scheme for a user’s own profile via AJAX.
wp_ajax_save_widget()`wp-admin/includes/ajax-actions.php`	Handles saving a widget via AJAX.
wp_ajax_upload_attachment()`wp-admin/includes/ajax-actions.php`	Handles uploading attachments via AJAX.
wp_ajax_image_editor()`wp-admin/includes/ajax-actions.php`	Handles image editing via AJAX.
wp_ajax_set_post_thumbnail()`wp-admin/includes/ajax-actions.php`	Handles setting the featured image via AJAX.
wp_ajax_wp_fullscreen_save_post()`wp-admin/includes/ajax-actions.php`	Handles saving posts from the fullscreen editor via AJAX.
wp_ajax_wp_remove_post_lock()`wp-admin/includes/ajax-actions.php`	Handles removing a post lock via AJAX.
wp_ajax_save_attachment()`wp-admin/includes/ajax-actions.php`	Handles updating attachment attributes via AJAX.
wp_ajax_save_attachment_compat()`wp-admin/includes/ajax-actions.php`	Handles saving backward compatible attachment attributes via AJAX.
wp_ajax_add_menu_item()`wp-admin/includes/ajax-actions.php`	Handles adding a menu item via AJAX.
wp_ajax_add_meta()`wp-admin/includes/ajax-actions.php`	Handles adding meta via AJAX.
wp_ajax_add_user()`wp-admin/includes/ajax-actions.php`	Handles adding a user via AJAX.
wp_ajax_closed_postboxes()`wp-admin/includes/ajax-actions.php`	Handles closed post boxes via AJAX.
wp_ajax_hidden_columns()`wp-admin/includes/ajax-actions.php`	Handles hidden columns via AJAX.
wp_ajax_update_welcome_panel()`wp-admin/includes/ajax-actions.php`	Handles updating whether to display the welcome panel via AJAX.
wp_ajax_wp_link_ajax()`wp-admin/includes/ajax-actions.php`	Handles internal linking via AJAX.
wp_ajax_menu_locations_save()`wp-admin/includes/ajax-actions.php`	Handles saving menu locations via AJAX.
wp_ajax_meta_box_order()`wp-admin/includes/ajax-actions.php`	Handles saving the meta box order via AJAX.
wp_ajax_get_permalink()`wp-admin/includes/ajax-actions.php`	Handles retrieving a permalink via AJAX.
wp_ajax_sample_permalink()`wp-admin/includes/ajax-actions.php`	Handles retrieving a sample permalink via AJAX.
wp_ajax_inline_save()`wp-admin/includes/ajax-actions.php`	Handles Quick Edit saving a post from a list table via AJAX.
wp_ajax_inline_save_tax()`wp-admin/includes/ajax-actions.php`	Handles Quick Edit saving for a term via AJAX.
wp_ajax_find_posts()`wp-admin/includes/ajax-actions.php`	Handles querying posts for the Find Posts modal via AJAX.
wp_ajax_widgets_order()`wp-admin/includes/ajax-actions.php`	Handles saving the widgets order via AJAX.
_wp_ajax_add_hierarchical_term()`wp-admin/includes/ajax-actions.php`	Handles adding a hierarchical term via AJAX.
wp_ajax_delete_comment()`wp-admin/includes/ajax-actions.php`	Handles deleting a comment via AJAX.
wp_ajax_delete_tag()`wp-admin/includes/ajax-actions.php`	Handles deleting a tag via AJAX.
wp_ajax_delete_link()`wp-admin/includes/ajax-actions.php`	Handles deleting a link via AJAX.
wp_ajax_delete_meta()`wp-admin/includes/ajax-actions.php`	Handles deleting meta via AJAX.
wp_ajax_delete_post()`wp-admin/includes/ajax-actions.php`	Handles deleting a post via AJAX.
wp_ajax_trash_post()`wp-admin/includes/ajax-actions.php`	Handles sending a post to the Trash via AJAX.
wp_ajax_delete_page()`wp-admin/includes/ajax-actions.php`	Handles deleting a page via AJAX.
wp_ajax_dim_comment()`wp-admin/includes/ajax-actions.php`	Handles dimming a comment via AJAX.
wp_ajax_add_link_category()`wp-admin/includes/ajax-actions.php`	Handles adding a link category via AJAX.
wp_ajax_add_tag()`wp-admin/includes/ajax-actions.php`	Handles adding a tag via AJAX.
wp_ajax_get_comments()`wp-admin/includes/ajax-actions.php`	Handles getting comments via AJAX.
wp_ajax_replyto_comment()`wp-admin/includes/ajax-actions.php`	Handles replying to a comment via AJAX.
wp_ajax_edit_comment()`wp-admin/includes/ajax-actions.php`	Handles editing a comment via AJAX.
wp_ajax_fetch_list()`wp-admin/includes/ajax-actions.php`	Handles fetching a list table via AJAX.
wp_ajax_wp_compression_test()`wp-admin/includes/ajax-actions.php`	Handles compression testing via AJAX.
wp_ajax_imgedit_preview()`wp-admin/includes/ajax-actions.php`	Handles image editor previews via AJAX.
Custom_Image_Header::ajax_header_crop()`wp-admin/includes/class-custom-image-header.php`	Gets attachment uploaded by Media Manager, crops it, then saves it as a new object. Returns JSON-encoded object details.
Custom_Image_Header::ajax_header_add()`wp-admin/includes/class-custom-image-header.php`	Given an attachment ID for a header image, updates its “last used” timestamp to now.
Custom_Image_Header::ajax_header_remove()`wp-admin/includes/class-custom-image-header.php`	Given an attachment ID for a header image, unsets it as a user-uploaded header image for the active theme.
Custom_Background::wp_set_background_image()`wp-admin/includes/class-custom-background.php`
WP_Customize_Manager::save()`wp-includes/class-wp-customize-manager.php`	Handles customize_save WP Ajax request to save/update a changeset.
WP_Customize_Manager::setup_theme()`wp-includes/class-wp-customize-manager.php`	Starts preview and customize theme.
WP_Customize_Widgets::wp_ajax_update_widget()`wp-includes/class-wp-customize-widgets.php`	Updates widget settings asynchronously.

Show 80 more Show less

Changelog

Version	Description
2.0.3	Introduced.

User Contributed Notes

Skip to note 2 content

Codex

11 years ago

Example
In your main file, set the nonce like this:



<script type="text/javascript">
jQuery(document).ready(function($){
	var data = {
		action: 'wpdocs_action',
		security: '<?php echo $ajax_nonce; ?>',
		wpdocs_string: 'Hello World!'
	};
	$.post(ajaxurl, data, function(response) {
		alert("Response: " + response);
	});
});
</script>

In your AJAX file, check the referrer like this:

/**
 * Check the referrer for the AJAX call.
 */
function wpdocs_action_function() {
	check_ajax_referer( 'wpdocs-special-string', 'security' );
	echo sanitize_text_field( $_POST['wpdocs_string'] );
	die;
}
add_action( 'wp_ajax_wpdocs_action', 'wpdocs_action_function' );

云策 WordPress 开发者社区

函数文档