ZNonce
Introduction
ZNonce library provides WordPress nonce functionality in more object-oriented way.
Nonces are used to help protect URLs and forms from certain types of misuse, malicious or otherwise.
Please see https://codex.wordpress.org/WordPress_Nonces for details., (*1)
Installation
The recomended way to install ZNonce is using composer:, (*2)
composer require zahardoc/z-nonce
How to use it
After installation ensure you required composer autoload.php file anywhere in your code before using ZNonce:, (*3)
require_once 'path/to/folder/vendor/autoload.php';
Then you could get ZNonce everywhere in your code using ZNonce::init() function:, (*4)
$znonce = Zahardoc\ZNonce\ZNonce::init();
Then you can create or verify a nonce., (*5)
Note that nonces has lifetime after which they expire. By default it is 24 hours, but you can modify it by set_nonce_life() method. Just call it with number of seconds you want nonce to live.
Example: set nonce time to 1 minute:, (*6)
$znonce->set_nonce_life(60);
Also, you can always check nonce life time by get_nonce_life():, (*7)
$life = $znonce->get_nonce_life();
Creating a nonce
When you creating a nonce try to use as more specific action as you can. For example, if you are dealing with post, add post id to your action. There are 3 ways to use creating a nonce functionality:, (*8)
Adding a nonce to a URL
To add a nonce to a URL, call nonce_url() method specifying the bare URL and a string representing the action:, (*9)
$action_url = $znonce->nonce_url( $bare_url, 'your_action_'.$post_id );
To add a nonce to a form, use nonce_field():, (*10)
$znonce->nonce_field( 'your_action_'.$post_id );
It will create 2 hidden fields with nonce and referer values, which you could verify later., (*11)
Creating a nonce for use in some other way
If you need nonce itself to use it in some other way, call create_nonce() method:, (*12)
$nonce = $znonce->create_nonce( 'your-action_'.$post_id );
Verifying a nonce
If nonce is valid, all verify methods return 1 or 2 depending on how much time ago it has been created. If it is less then half of expire time - method returns 1, otherwise - 2., (*13)
Verifying a nonce passed from an admin screen
To verify a nonce passed from an admin screen, call check_admin_referer() specifying the string representing the action., (*14)
$znonce->check_admin_referer( 'your_action' );
This call checks the nonce and the referrer, and if the check fails it terminates script execution with a "403 Forbidden" response and an error message., (*15)
Verifying a nonce passed in an AJAX request
To verify a nonce passed from an AJAX request, call check_ajax_referer() method specifying the string representing the action., (*16)
$znonce->check_ajax_referer( 'your_action' );
This call checks the nonce (but not the referrer), and if the check fails then it terminates script execution., (*17)
Verifying a nonce passed in some other context
If you want just verify a nonce and then do some of your custom actions, use verify_nonce() method:, (*18)
$result = $znonce->verify_nonce( $_REQUEST['your_nonce'], 'your-action_'.$post_id );
Testing
ZNonce is provided with phpunit tests. To run them, please follow these steps:, (*19)
- Go to the library root directory:
cd /your/vendor/path/zahardoc/z-nonce
- Install environment
tests/install.sh <db-name> <db-user> <db-pass> [db-host] [wp-version]
Note: use database user with privileges to create new database. Don't specify existing database here.
- Install library dependencies:
composer update
- Run tests:
vendor/bin/phpunit
License
This library is released under the MIT license, you can use it free of charge on your personal or commercial sites., (*20)
Wallogit.com
