Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Standard PHP Library and Classes

The Random\Engine classes

Reference for PHP Random\Engine classes: Secure, Mt19937, PcgOneseq128XslRr64 and Xoshiro256StarStar, seeding, cloning, serializing and writing your own engine.

A random engine is an object that produces a stream of random bytes. PHP 8.2 added the Random\Engine interface and four ready-made engines in the Random\Engine namespace. You rarely call an engine directly: you give it to a Random\Randomizer, which turns the raw bytes into integers, floats, shuffles and picks.

Pick Secure when unpredictability matters (tokens, passwords, anything an attacker could exploit). Pick a seeded engine when you need a repeatable sequence: tests, simulations, procedural generation.

Engine Seedable Cloneable and serializable Use for
Secure no no Security-sensitive randomness (the default of Randomizer).
Mt19937 yes yes Reproducible sequences from the classic Mersenne Twister.
PcgOneseq128XslRr64 yes yes Fast, good statistical quality, supports jump().
Xoshiro256StarStar yes yes Fast, good quality, supports jump() and jumpLong().

Try it

PHP Seeded engines repeat, Secure does not

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Cloning, serializing and seed errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
interface Random\Engine
{
    public function generate(): string;
}

new Random\Engine\Secure();
new Random\Engine\Mt19937(?int $seed = null, int $mode = MT_RAND_MT19937);
new Random\Engine\PcgOneseq128XslRr64(string|int|null $seed = null);
new Random\Engine\Xoshiro256StarStar(string|int|null $seed = null);
Name Description
$seed Integer, or for PCG a 16-byte string and for Xoshiro a 32-byte string. null seeds from the system's secure source.
$mode Mt19937 only: MT_RAND_MT19937 (the correct algorithm). MT_RAND_PHP is deprecated since PHP 8.3.
generate() Returns the next chunk of random bytes as a string (4 bytes for Mt19937, 8 for PCG and Xoshiro).
jump($advanceBy) PCG only. Moves the sequence forward by that many steps, so parallel workers can use disjoint streams.
jump(), jumpLong() Xoshiro only. Skip far ahead in the sequence (2^128 and 2^192 steps).

Return value: generate() returns a string of raw bytes. Constructors return the engine object.

Errors / Exceptions: ValueError for a string seed of the wrong length or an invalid $mode. Secure throws Random\RandomException if no source of randomness is available.

Usage notes

  • Same seed, same sequence, on every machine. That is the point of a seeded engine and the reason tests use one.
  • Never use seeded engines for secrets. Their output can be predicted from a few values. Use Secure, random_int() or random_bytes().
  • Engines are objects, not globals. Two engines with the same seed advance independently; mt_srand() does not affect them.
  • Clone to branch a sequence, for example to replay from a checkpoint. serialize() stores the state if you need to save it.
  • Each Randomizer call may consume several engine steps (range mapping uses rejection sampling to avoid bias), so do not count on one step per value.
  • Integer seeds are limited. A 64-bit integer holds far less than the engine's full state. Use a long random string seed (for example random_bytes(32) or a hash) if you want the engine's full range.
  • Custom engines: implement Random\Engine (and Random\CryptoSafeEngine only if the output is cryptographically secure) and return a string from generate() containing 1 to 8 bytes.
  • Added in PHP 8.2.