check_ajax_referer()WP 2.0.3

Verifies nonce token of an Ajax request. Kills PHP if the verification failed. By default searches for a nonce token in $_REQUEST['_ajax_nonce'] and $_REQUEST['_wpnonce'].

Pluggable function — this function can be replaced from a plugin. It means that this function is defined (works) only after all plugins are loaded (included), but before this moment this function has not defined. Therefore, you cannot call this and all functions depended on this function directly from a plugin code. They need to be called on plugins_loaded hook or later, for example on init hook.

Function replacement (override) — in must-use or regular plugin you can create a function with the same name, then it will replace this function.

Hooks from the function

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.

Usage

check_ajax_referer( $action, $query_arg, $die );
$action(int/string)
Action nonce. Specified when creating nonce: wp_create_nonce("my_action").
Default: -1
$query_arg(false/string)
Key to check for the nonce in $_REQUEST. If false, $_REQUEST values will be evaluated for '_ajax_nonce', and '_wpnonce' (in that order).
Default: false
$die(true/false)

Whether to die when the nonce cannot be verified.

  • true - error message will be -1. If it's an ajax request, error title (see wp_die()) will be 403 (forbidden).

  • false - PHP will not die and the function will return false/Int depending on the result.
    Default: true

Examples

0

#1 Creation and verification of nonce token in AJAX request

In the main file we set nonce like this:

<?php
// Creating Nonce (you can do it in several file). here it's in one "file" for convenience
$ajax_nonce = wp_create_nonce("my-special-string");
?>

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

It is Better use wp_localize_script() for transfering nonce token to JS, and store JS code in a separate file that will be loaded with wp_enqueue_script()

Then, we check the nonce string when processing the Ajax request:

add_action( 'wp_ajax_my_action', 'my_action_function' );
function my_action_function() {
	check_ajax_referer( 'my-special-string', 'security' );
	echo $_POST['my_string'];
	die;
}

Here we have created a nonce token with my-special-string action and have verified it.

You can use _wpnonce or _ajax_nonce instead of security in JS, so the value grabbed automatically by check_ajax_referer() function, and you have no need to specify the second argument.

Changelog

Since 2.0.3 Introduced.

check_ajax_referer() code WP 6.4.3

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;
}