Codex

Function Reference/check admin referer

Contents

Description

Tests if the current request was referred from an admin page, or (given $action parameter) if the current request carries a valid nonce. Used to avoid security exploits.

Usage

<?php check_admin_referer( $action, $query_arg ); ?>

Parameters

$action
(string) (defaults to int -1) Action nonce
Default: -1
$query_arg
(string) (optional) where to look for nonce in $_REQUEST (since 2.5)
Default: '_wpnonce'

Return Values

(??) 
Function dies if not referred from admin page, returns boolean true if the admin referer was was successfully validated.

(This is arguably strange behavior: it does not conform to a classifiable type of return values)

This page is marked as incomplete. You can help Codex by expanding it.

Examples

Simplistic usage here:  <?php check_admin_referer( 'bcn_admin_options' ); ?>  (Script dies if the admin referer is not validated).

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

Change Log

Since: 1.2.0

Related

See also index of Function Reference and index of Template Tags.
Retrieved from "http://codex.wordpress.org/Function_Reference/check_admin_referer"

Codex Resources