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
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.
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
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()orrandom_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
Randomizercall 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(andRandom\CryptoSafeEngineonly if the output is cryptographically secure) and return a string fromgenerate()containing 1 to 8 bytes. - Added in PHP 8.2.