Download the PHP package michaelfrank-dev/php-trng without Composer

PHP TRNG

[]()

PHP library for retrieving True Random Numbers (TRNG) from multiple external hardware and quantum entropy sources.

Whether you need true, non-deterministic random numbers for cryptographic seeding, randomized trials, simulations, or procedural generation, this library provides a clean interface to fetch uint8 or uint16 integers natively. It features granular exception handling to allow resilient fallback chains.

Features

• Multiple Entropy Sources: Native support for RANDOM.ORG, ANU Quantum Random Numbers, and the Drand Distributed Randomness Beacon.
• Unbiased Range Generation: Includes an EntropyBuffer that derives specific types, bounds, and ranges safely without modular bias (rejection sampling).
• Flexible Authentication: Most providers can be configured with or without API keys, adapting to your usage volume and tier.
• Smart Limitations Bypass: Gracefully unpacks values behind the scenes when service quotas restrict payload limits (e.g., doubling uint8 output limits on ANU).

Installation

Install via Composer:

PSR-18 Requirement: This package requires a PSR-18 HTTP Client and PSR-17 HTTP Factories. If you don't already have one in your project, install Guzzle:

64-bit PHP Required: EntropyBuffer::toInteger(8) reads a 64-bit unsigned integer using unpack('J', ...). On a 32-bit PHP build, values exceeding PHP_INT_MAX are silently returned as floats, breaking type safety. This library requires a 64-bit PHP build.

Fetching Raw Random Numbers

The simplest use case is fetching raw random integers directly from a provider. All providers implement a getValues(int $length, TrngType $type) method that returns a plain PHP array.

RANDOM.ORG

Can be used with or without an API key.

• Without an API Key — uses the legacy plain-text API.
• With an API Key — upgrades to the JSON-RPC v4 API for higher limits and quota telemetry.

Terms of Use: The RANDOM.ORG open API is subject to fair-use rate limits and other restrictions. Review the usage guidelines before integrating it into production applications.

ANU Quantum Random Numbers (QRNG)

Can be used with or without an API key.

Deprecation Notice: The unauthenticated ANU endpoint (qrng.anu.edu.au) is being phased out and may be unavailable in the future. It is strongly recommended to register for an API key and use AnuProvider::withApiKey() for any production usage.

Note on API Limits: The ANU API enforces a strict limit of 1,024 items per request. When you request more than 1,024 uint8 values, the library automatically requests uint16 from the API and unpacks them internally, yielding up to 2,048 uint8 values transparently.

Drand (Distributed Randomness Beacon)

Drand yields exactly 32 bytes (or 16 uint16 values) per beacon call. No API key is required. The beacon signature is verified automatically to ensure cryptographic integrity. Note: It does not verify the drand BLS signature against the chain public key.

This provider targets the Quicknet chain by default (QUICKNET_CHAIN_HASH), which operates on a 3-second pulse interval with unchained, threshold BLS randomness.

Consuming Entropy Safely with EntropyBuffer

Raw random integers are useful on their own, but using modulo (%) to fit them into a range introduces modular bias, which skews the distribution. The EntropyBuffer class solves this by using rejection sampling to guarantee a perfectly uniform distribution.

Important: EntropyBuffer operates on bytes (uint8, values 0-255). If you fetched uint16 values from a provider, you must convert them first using EntropyBuffer::fromUint16().

Example: From uint8 (direct)

Example: From uint16 (use the helper)

When you fetch uint16 values from a provider, pass them through EntropyBuffer::fromUint16(). It splits each 16-bit integer into two bytes (Big Endian) and returns a ready-to-use buffer with double the entropy.

Passing uint16 values directly to new EntropyBuffer() will throw an \InvalidArgumentException, as the constructor enforces that all values are valid bytes (0-255).

Exception Handling & Fallback Chains

When working with external HTTP APIs, resilient error handling is critical. The library defines granular exceptions that all extend the base TrngException class.

The example below demonstrates a complete three-tier fallback chain across all providers:

License

This library is open-sourced software licensed under the MIT license.