WordPress Nonce Service

You ever wondered, how to handle nonces in WordPress more easily? Well, here you go: A handy service class, that acts like a wrapper for all of WordPress' nonce core functionality.

Preamble

You need composer running with WordPress. There are different ways to use both together. The setup used for this package has a folder structure like this:

root/
    composer.json
    composer.lock
    public/
        [WordPress root]
    vendor/

However, you can use this package with any other way to combine Composer and WordPress.

Requirements

To run the Nonce Service smoothly your environment should meet these requirements:

• PHP 7.2
• WordPress 4.9.x

In addition to run tests, you also need:

• PHPUnit 7

Installation

Install with Composer:

$ composer require insertusernamehere/wp-nonce-service

Setup

If you don't have Composer's autoloader running in Wordpress already, here's one way to add it:

require get_home_path() . '../vendor/autoload.php';

See WordPress' Function Reference get_home_path() for more information.

Basic Usage

Create a Nonce Service object:

use insertusernamehere\NonceService\Nonce_Service;

$nonce_service = new Nonce_Service();

Get the current tick

$nonce_service->tick();

For more information see: wp_nonce_tick().

Create a nonce

$nonce_service->create();

With the optional $action-parameter:

$nonce_service->create(1);
$nonce_service->create('update-post');

Invalid calls, see "Important note on the $action-parameter" for more information:

$nonce_service->create('');
$nonce_service->create(1.0);

For more information see: wp_create_none().

Append nonce to URL

$nonce_service->append_to_url();

For more information see: wp_nonce_url().

Create a hidden nonce-field with optional referer-field

$nonce_service->create_field();

Opposed to the original wp_nonce_field() this function has only three arguments and no option to echo the field directly. This should be handled by your template engine.

For more information see: wp_nonce_field().

Run a confirmation dialog

$nonce_service->run_confirmation();

This function can display a "Do you really want to logout" message as well, if you set $action to "log-out".

For more information see: wp_nonce_ays().

Verify a nonce

$nonce_service->verify();

Opposed to WordPress' original wp_verify_nonce()-function, this function always returns a value of type int. In case of failure the return value is 0 instead of false.

For more information see: wp_verify_nonce().

Important note on the $action-parameter

A lot of methods make use of the optional $action-parameter. To avoid unintentional type casts, resulting in unexpected results, the action-parameter is handled stricter than in the original WordPress core. The value must be of type int or string.

On top of that an empty string is also invalid and will be blocked by this script, to avoid misinterpretation with the default value, which is -1.

Running tests

The tests for the Nonce Service are based on PHPUnit 7. To sucessfully run the test, you need WordPress' WP-CLI installed and running.

There's a helper class Nonce_ServiceTestRunner which bootstraps the tests programatically in the WordPress environment.

To run all tests simply execute:

$ wp eval "insertusernamehere\NonceService\Test\Nonce_ServiceTestRunner::runTest();"

Bugs and feature request are tracked on GitHub

Please report bugs and submit feature requests through GitHub.

License

MIT license