Function Reference/check admin referer

来自WordPress中文文档
跳转至: 导航搜索

Description

Tests either if the current request carries a valid nonce, or if the current request was referred from an administration screen; depending on whether the $action argument is given (which is prefered), or not, respectively. On failure, the function dies after calling the wp_nonce_ays() function.

Used to avoid security exploits.

The now improper name of the function is kept for backward compatibility and has origin in previous WordPress versions where the function only checked the referer. For details, see the Notes section below.

Usage

Obsolete Usage

%%%<?php check_admin_referer(); ?>%%%

Prefered Usage

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

Parameters

tt$action/tt
(string) (optional) Action name. Should give the context to what is taking place. (Since 2.0.1).
Default: -1noinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

tt$query_arg/tt
(string) (optional) Where to look for nonce in the $_REQUEST PHP variable. (Since 2.5).
Default: '_wpnonce'noinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

Return

To return boolean true, in the case of the obsolete usage, the current request must be referred from an administration screen; in the case of the prefered usage, the nonce must be sent and valid. Otherwise the function dies with an appropriate message ("Are you sure you want to do this?" by default).

Examples

Obsolete usage here (script dies if the admin referer is not validated).

<?php check_admin_referer(); ?>

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

Notes

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

Change Log

Since: 1.2.0

Source File

check_admin_referer() is located in onlyincludecodewp-includes/pluggable.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre检查到模板循环:模板:Trac/pre

Link to trunk: pre检查到模板循环:模板:Trac/pre

/div

wordpress.org.cn.

Related

模板:Nonces

Resources

includeonlydiv style=clear:both; background-color:#F7F7F7; border:1px solid #CCCCCC; color:#000000; padding:7px; margin:0.5em auto 0.5em auto; vertical-align:middle;See also index of Function Reference and index of Template Tags./div/includeonlynoinclude

Description

This Template is used by Codex:Template Messages.

Usage

pre 检查到模板循环:模板:Message /pre

Result

检查到模板循环:模板:Message

/noinclude