PHPackages                             brain/nonces - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. brain/nonces

ActivePackage[Security](/categories/security)

brain/nonces
============

OOP package for WordPress to deal with nonces.

1.0.6(1y ago)25237.0k↓44.9%71MITPHPPHP >=7.1

Since Oct 12Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/Brain-WP/Nonces)[ Packagist](https://packagist.org/packages/brain/nonces)[ RSS](/packages/brain-nonces/feed)WikiDiscussions master Synced 3d ago

READMEChangelog (7)Dependencies (4)Versions (8)Used By (1)

Nonces
======

[](#nonces)

[![Travis CI](https://camo.githubusercontent.com/658f244761596c2526259e07e3e7fcd7f0a17fe6aa614c8db019d95f65bed3a4/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f427261696e2d57502f4e6f6e6365732e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/Brain-WP/Nonces)[![codecov.io](https://camo.githubusercontent.com/b072bb29b8590e19bb3fad19063c208b2282b0739e63ccfea7bdc71dd3b8fe93/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f427261696e2d57502f4e6f6e6365732e7376673f7374796c653d666c61742d737175617265)](https://codecov.io/github/Brain-WP/Nonces)[![MIT license](https://camo.githubusercontent.com/8d675896792fe128f3bfddb6077db973c6629d24c46614846876dc9d939ad173/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f627261696e2f6e6f6e6365732e7376673f7374796c653d666c61742d737175617265)](http://opensource.org/licenses/MIT)

---

**Nonces is an OOP package for WordPress to deal with nonces.**

---

TOC

- [Introduction](#Introduction)
- [How it works](#how-it-works)
    - [Rethinking WordPress workflow](#rethinking-wordpress-workflow)
    - [`NonceInterface` and `WpNonce`](#nonceinterface-and-wpnonce)
    - [Nonce context](#nonce-context)
    - [`RequestGlobalsContext`](#requestglobalscontext)
    - [`Helpers`](#helpers)
    - [`WpNonce` is blog-specific](#wpnonce-is-blog-specific)
- [Installation](#installation)
- [Minimum Requirements](#minimum-requirements)
- [License](#license)
- [Contributing](#contributing)

---

Introduction
============

[](#introduction)

WordPress nonces functions does not really work well in an OOP context.

They needs "keys" and "actions" to be passed around, ending up in code that hardcodes those strings in classes code, or stores them in globally accessible place.

Both solutions are not ideal.

This package aims to provide a way to ease WordPress nonces usage in OOP code.

The specific issues that are addressed are:

- avoid dealing with somehow hardcoded nonce "keys" and "actions"
- have a way to customize nonce TTL on a per nonce basis
- have an approach more suitable for OOP, with enough flexibility to be extended with different implementations of nonces

How it works
============

[](#how-it-works)

Rethinking WordPress workflow
-----------------------------

[](#rethinking-wordpress-workflow)

*WordPress* nonces workflow is:

1. For a "task" a nonce key and an nonce value are put in a request (as URL query variable or via hidden form field). The "key" is just hardcoded, the value is generated with `wp_create_action()`and it is an hash based on an "action" that is specific for the "task";
2. The request handler extracts the nonce value from request data (so it needs to be aware of the nonce "key") and validates it with `wp_verify_nonce()` that needs to be aware the "action".

What we wanted to avoid is to have "keys" and "actions" that needs to be known where the nonce is *created* **and** where it is *validated*, causing the issue of tightly coupling between different parts of the code as well as the more pragmatic issue of a place to store those values, or to have them just hardcoded.

*This package* workflow is:

1. For a "task" a nonce object is created, passing an action string to constructor. There's no "key" and the "action" is not needed to be known anywhere else.
2. The request handler, needs to receive (as method argument or as a dependency injected to constructor) an instance of the nonce task and use that object ot validate the request.

So, using this package, the workflow would be something like (pseudo code):

```
class TaskForm {

   public function __construct(\Brain\Nonces\NonceInterface $nonce){
     $this->nonce = $nonce;
     $this->url = admin_url('admin-post.php');
   }

   public function printFrom() {
      $url = add_query_arg($this->nonce->action(), (string) $this->nonce, $this->url);
      echo "";
      // rest of form here...
   }
}

class TaskFormHandler {

   public function __construct(\Brain\Nonces\NonceInterface $nonce){
     $this->nonce = $nonce;
   }

   public function saveForm() {
      if (! $this->nonce->validate()) {
        // handle error here...
      }

      // continue processing here...
   }
}
```

So the code responsible to build the form and the code responsible to process it, knows nothing about "keys" or "actions", nor there's any string hardcoded anywhere.

`NonceInterface` and `WpNonce`
------------------------------

[](#nonceinterface-and-wpnonce)

The two classes on the example above receives an instance on `NonceInterface`.

That interface has 3 methods:

- `action()`
- `__toString()`
- `validate()`

The package ships with just one implementation that is called `WpNonce` and wraps WordPress functions to create and validate the nonce.

Nonce context
-------------

[](#nonce-context)

The `validate()` method of `NonceInterface` receives an optional parameter: an instance of `NonceContextInterface`.

The reason is that to validate the value it encapsulates, a nonce needs to know what to compare the the value to.

This package calls this value to be compared with nonce value "context".

Nonce context is represented by a very simple interface that is no more than an extension of `ArrayAccess`.

The reason is that even if WordPress implementation of nonces requires a string as "context" other implementations may require different / more things.

For example, I can imagine a nonce implementation that stores nonce values as user meta, and to verify that nonce is valid would require not only the value itself, but also an user ID.

Making the context an `ArrayAccess` instance, the package provides as much flexibility as possible for custom implementations.

`RequestGlobalsContext`
-----------------------

[](#requestglobalscontext)

In the sample pseudo code above, `validate()` is called without passing any context.

The reason is than when not provided (as it is optional) `WpNonce` creates and uses a default implementation of `NonceContextInterface` that is `RequestGlobalsContext`.

This implementation uses super globals (`$_GET` and `$_POST`) to "fill" the `ArrayAccess` storage so that `validate()` will actually uses values from super globals as context when no other context is provided.

Being this the most common usage of nonces in WordPress, this simplify operations in large majority of cases, still providing flexibility for even very custom implementations.

Just for example, it would be very easy to build a `NonceContextInterface` implementation that takes its value from HTTP headers (could be useful in REST context), still being able to use the `WpNonce` class shipped with this package to validate it.

Helpers
-------

[](#helpers)

Looking at the sample pseudo code above, when there was the need to "embed" the nonce in the HTML form, the code uses `add_query_arg()` to add the nonce action and value as URL query variable.

This is something that in core is done with `wp_nonce_url()`, however, that function takes as arguments "action" and "key" as string and build the nonce value itself.

Since we want encapsulate the creation of nonce value we can't really use that function.

To provide the same level of "easiness", this package provides a function **`Brain\Nonces\nonceUrl()`**that receives a nonce instance and an URL string and add the nonce action / value as URL query variable.

The nonce instance is the first function argument and, unlike for WordPress core function, the URL string is optional and if not provided defaults to current URL.

However, in case of HTML forms, it is probably better to use a form field instead of a URL query variable.

In WordPress that is done using `wp_nonce_field()`, this package provides **`Brain\Nonces\formField()`**that receives a nonce instance and *returns* the form field HTML markup.

So, the above sample pseudo code could be updated like this:

```
class TaskForm {

   public function __construct(\Brain\Nonces\NonceInterface $nonce){
     $this->nonce = $nonce;
     $this->url = admin_url('admin-post.php');
   }

   public function printFrom() {
      $url = \Brain\Nonces\nonceUrl($this->nonce, $this->url);
      echo "";
      // rest of form here...
   }
}
```

or even better like this:

```
class TaskForm {

   public function __construct(\Brain\Nonces\NonceInterface $nonce){
     $this->nonce = $nonce;
     $this->url = admin_url('admin-post.php');
   }

   public function printFrom() {
      echo "url}>";
      echo \Brain\Nonces\formField($this->nonce);
      // rest of form here...
   }
}
```

Note that these two helpers accept an instance of `NonceInterface` and not of WordPress specific `WpNonce` class, so they can be used with any custom implementation as well.

`WpNonce` is blog-specific
--------------------------

[](#wpnonce-is-blog-specific)

It is said above that the `WpNonce` class is a wrapper around WordPress functions.

It is true, but besides of using `wp_create_nonce()` / `wp_verify_nonce()`, `WpNonce` automatically adds to the action passed to its constructor the current blog id, when calling both those WordPress functions.

This ensures that when a nonce was generated in a blog context, will fail validating under another blog context.

This is a sanity check that avoid different issues in multisite context with plugins that switch blog when, for example, saving post data; preventing to save meta data for posts of a blog into posts of *another* blog.

Installation
============

[](#installation)

Via Composer, require `brain/nonces` in version `~1.0.0`.

Minimum Requirements
====================

[](#minimum-requirements)

- PHP 5.5+
- Composer to install

License
=======

[](#license)

MIT

Contributing
============

[](#contributing)

See `CONTRIBUTING.md`.

**Don't** use issue tracker (nor send any pull request) if you find a **security** issue. They are public, so please send an email to the address on my [Github profile](https://github.com/Giuseppe-Mazzapica). Thanks.

###  Health Score

51

—

FairBetter than 95% of packages

Maintenance66

Regular maintenance activity

Popularity44

Moderate usage in the ecosystem

Community18

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 84.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~528 days

Recently: every ~792 days

Total

7

Last Release

381d ago

PHP version history (2 changes)1.0.0PHP >=5.5.0

1.0.6PHP >=7.1

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2208282?v=4)[Giuseppe Mazzapica](/maintainers/gmazzap)[@gmazzap](https://github.com/gmazzap)

---

Top Contributors

[![gmazzap](https://avatars.githubusercontent.com/u/2208282?v=4)](https://github.com/gmazzap "gmazzap (16 commits)")[![AlexP11223](https://avatars.githubusercontent.com/u/5680466?v=4)](https://github.com/AlexP11223 "AlexP11223 (1 commits)")[![amiut](https://avatars.githubusercontent.com/u/25235298?v=4)](https://github.com/amiut "amiut (1 commits)")[![Soean](https://avatars.githubusercontent.com/u/695201?v=4)](https://github.com/Soean "Soean (1 commits)")

---

Tags

nonceswordpresswordpresssecuritynoncewordpress nonce

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/brain-nonces/health.svg)

```
[![Health](https://phpackages.com/badges/brain-nonces/health.svg)](https://phpackages.com/packages/brain-nonces)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)