check_admin_referer( int|string $action = -1, string $query_arg = '_wpnonce' ): int|false
Ensures intent by verifying that a user was referred from another admin page with the correct security nonce.
Contents
Description
This function ensures the user intends to perform a given action, which helps protect against clickjacking style attacks. It verifies intent, not authorization, therefore it does not verify the user’s capabilities. This should be performed with current_user_can() or similar.
If the nonce value is invalid, the function will exit with an "Are You Sure?" style message.
Parameters
-
$actionint|string Optional -
The nonce action.
Default:
-1 -
$query_argstring Optional -
Key to check for nonce in
$_REQUEST. Default'_wpnonce'.Default:
'_wpnonce'
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
- Using the function without the
$actionargument is obsolete and, as of Version 3.2, ifWP_DEBUGis set totrue, the function will die with an appropriate message (“You should specify a nonce action to be verified by using the first parameter.” is the default). - As of 2.0.1, the referer is checked only if the
$actionargument is not specified (or set to the default -1) as a backward compatibility fallback for not using a nonce. A nonce is prefered to unreliable referers and with$actionspecified the function behaves the same way as wp_verify_nonce() except that it dies after calling wp_nonce_ays() if the nonce is not valid or was not sent.
Source
File: wp-includes/pluggable.php.
View all references
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 && strpos( $referer, $adminurl ) === 0 ) ) {
wp_nonce_ays( $action );
die();
}
return $result;
}
Hooks
-
do_action( 'check_admin_referer',
string $action ,false|int $result ) -
Fires once the admin request has been validated or not.
Changelog
| Version | Description |
|---|---|
| 2.5.0 | The $query_arg parameter was added. |
| 1.2.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Usage in a plugin’s option page
Here is an example of how you might use this in a plugin’s option page. You add a nonce to a form using the wp_nonce_field() function:
Then in the page where the form submits to, you can verify whether or not the form was submitted and update values if it was successfully submitted:
Note – Obsolete usage
script dies if the admin referer is not validated.