WordPress at a glance

wp_nonce_field() WP 2.0.4

Retrieve or display hidden nonce field for a form.

The nonce field is used to validate that the contents of the form came from the location on the current site and not somewhere else. The nonce does not offer absolute protection, but should protect against most cases. It is very important to use nonce field in forms.

The $action and $name are optional, but if you want to have better security, it is strongly suggested to set those two parameters. It is easier to just call the function without any parameters, because validation of the nonce doesn't require any parameters, but since crackers know what the default is it won't be difficult for them to find a way around your nonce and cause damage.

The input name will be whatever $name value you gave. The input value will be the nonce creation value.

Works based on: wp_create_nonce()
✈ 1 time = 0.00011s = fast | 50000 times = 1.57s = fast

No Hooks.

Return

String. Nonce field HTML markup.

Usage

wp_nonce_field( $action, $name, $referer, $echo );
$action(int/string)
Action name. The nonce token is generated based on it.
Default: -1
$name(string)
The value of the name attribute of the input HTML tag. The value of the field can be taken from $_POST[ $name ] variable.
Default: '_wpnonce'
$referer(true/false)
Whether to set a referer field for validation. Hidden referer field can be added along with the nonce field. Also, such referer field can be added separately with wp_referer_field() function.
Default: true
$echo(true/false)
false — don't print, return the data to the variable for further handling.
Default: true

Examples

#1 Form data verification

<?php wp_nonce_field(); ?>

Output:

output: <input type="hidden" id="_wpnonce" name="_wpnonce" value="5284708911" />
<input type="hidden" name="_wp_http_referer" value="/permalink" />

#2 Better security

For better security you can use $action and $name parameters:

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

After the form data has been sent, when handling the data the nonce code must be verified with wp_verify_nonce() function. Like so:

<?php
if ( empty($_POST) || ! wp_verify_nonce( $_POST['name_of_nonce_field'], 'name_of_my_action') ){
   print 'Verification failed. Try again.';
   exit;
}
else {
   // Data handling
}

#3. Verification in the admin

If request data is received in the admin panel, it can be verified with check_admin_referer() function. If the verification has not been passed, then check_admin_referer() automatically print the error message and stop the further PHP execution — so there's no need to specify what to do if the verification is failed.

function my_handler_function(){

	// verification
	// On failed verification, prints a error message and kills PHP execution.
	check_admin_referer( 'name_of_my_action', 'name_of_nonce_field' );

	// data handling
}

Code of wp nonce field: wp-includes/functions.php VER 5.0.3

<?php
function wp_nonce_field( $action = -1, $name = "_wpnonce", $referer = true , $echo = true ) {
	$name = esc_attr( $name );
	$nonce_field = '<input type="hidden" id="' . $name . '" name="' . $name . '" value="' . wp_create_nonce( $action ) . '" />';

	if ( $referer )
		$nonce_field .= wp_referer_field( false );

	if ( $echo )
		echo $nonce_field;

	return $nonce_field;
}

Related Functions

From tag: nonce (security protection defence)

More from tag: Site security (safety)

No comments
    Hello, !     Log In . Register