check_admin_referer( int|string $action = -1, string $query_arg = '_wpnonce' )

Ensures intent by verifying that a user was referred from another admin page with the correct security nonce.


Description Description

This function ensures the user intends to perform a given action, which helps protect against clickjacking style attacks. It verifies intent, not authorisation, 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.


Top ↑

Parameters Parameters

$action

(int|string) (Optional) The nonce action.

Default value: -1

$query_arg

(string) (Optional) Key to check for nonce in $_REQUEST.

Default value: '_wpnonce'


Top ↑

Return 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.


Top ↑

More Information More Information

  • Using the function without the $action argument is obsolete and, as of Version 3.2, if WP_DEBUG is set to true, 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 $action argument 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 $action specified 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.

Top ↑

Source Source

File: wp-includes/pluggable.php

	function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
		if ( -1 === $action ) {
			_doing_it_wrong( __FUNCTION__, __( 'You should specify a nonce 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;
	}


Top ↑

Changelog Changelog

Changelog
Version Description
2.5.0 The $query_arg parameter was added.
1.2.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Codex

    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:

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

    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:

    <?php
    // if this fails, check_admin_referer() will automatically print a "failed" page and die.
    if ( ! empty( $_POST ) && check_admin_referer( 'name_of_my_action', 'name_of_nonce_field' ) ) {
       // process form data, e.g. update fields
    }
    
    // Display the form
    

You must log in before being able to contribute a note or feedback.