WordPress at a glance

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'].

This is a pluggable function, and it can be replaced by 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 a plugin you can create a function with the same name, then it replace this function.

Works based on: wp_verify_nonce()
Hooks from the function
Return

false/Int. 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.

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

#1 Creation and verification of nonce token in AJAX request

Creation:

<?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()

Verification:

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.

Code of check ajax referer: wp-includes/pluggable.php WP 5.2.2

<?php
function check_ajax_referer( $action = -1, $query_arg = false, $die = true ) {
	if ( -1 == $action ) {
		_doing_it_wrong( __FUNCTION__, __( 'You should specify a nonce action to be verified by using the first parameter.' ), '4.7' );
	}

	$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 ( $die && false === $result ) {
		if ( wp_doing_ajax() ) {
			wp_die( -1, 403 );
		} else {
			die( '-1' );
		}
	}

	return $result;
}

Related Functions

From tag: AJAX

More from tag: nonce (security protection defence)

More from category: Security

No comments
    Hello, !     Log In . Register