check_admin_referer() │ WP 1.2.0

Makes sure that a user was referred from another admin page. Сhecks a nonce token. Stops php with die() in case of error.

If one of the checks failed, shows a message: "Are you sure you want to do this?" with a link to the previous page, and then runs die() to stop further PHP execution. Read more in wp_nonce_ays().

Note about this function: Actually, if the nonce is valid the referrer should not be checked. The unreliability of referrers is one of the reasons that nonces are used. Nonces replace referrer checking entirely. The only time we check the referrer is when handling the -1 backward compatibility condition. -1 means that someone is not using nonces so we fall back to referrer checking. This usage is now very rare. check_admin_referer() is badly named now that it almost never does referrer checking. It would be better-named something like check_nonce(), but we keep it as is for back compat and old times sake.

There's also a similiar function for AJAX requests: check_ajax_referer()

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.

  • false — wrong nonce code.
  • 1 — nonce correct and was created 0-12 hours ago.
  • 2 — nonce correct and was created 12-24 hours ago.

Usage

check_admin_referer( $action, $query_arg );
$action(int/string)
Action nonce (the first argument of wp_nonce_field).
Default: -1
$query_arg(string)
Key to check for nonce in $_REQUEST (since 2.5).
Default: '_wpnonce'

Examples

0

#1 Basic example 

<?php check_admin_referer( 'bcn_admin_options' ); ?>

Further PHP execution will be stopped if the request was made not from the dashboard.

0

#2 Adding and verifying of nonce token

Let's add a nonce token and referer field into the form with wp_nonce_field():

<form method="post">
	<!-- other fields ... -->
	<?php wp_nonce_field( 'name_of_my_action','name_of_nonce_field' ); ?>
</form>

Now, on the page where the request is handled, check the nonce token and referer, and process the request if the check is passed:

function my_handler_function(){
	check_admin_referer( 'name_of_my_action', 'name_of_nonce_field' );

	// process request
}

Or you can use if() for better readability:

if( check_admin_referer( 'name_of_my_action', 'name_of_nonce_field' ) ) {
   // process request
}

Changelog

Since 1.2.0 Introduced.
Since 2.5.0 The $query_arg parameter was added.

check_admin_referer() code WP 6.5.2

wp-includes/pluggable.php 
function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
	if ( -1 === $action ) {
		_doing_it_wrong( __FUNCTION__, __( 'You should specify an action to be verified by using the first parameter.' ), '3.2.0' );
	}

	$adminurl = strtolower( admin_url() );
	$referer  = strtolower( wp_get_referer() );
	$result   = isset( $_REQUEST[ $query_arg ] ) ? wp_verify_nonce( $_REQUEST[ $query_arg ], $action ) : false;

	/**
	 * Fires once the admin request has been validated or not.
	 *
	 * @since 1.5.1
	 *
	 * @param string    $action The 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_admin_referer', $action, $result );

	if ( ! $result && ! ( -1 === $action && str_starts_with( $referer, $adminurl ) ) ) {
		wp_nonce_ays( $action );
		die();
	}

	return $result;
}

nonce (security protection defence)

Security