PHP Reference ยท Math Functions
The Random\Randomizer class
Reference for PHP Random\Randomizer: pluggable and seedable random engines, getInt, getFloat, shuffleArray, pickArrayKeys, getBytes and secure defaults.
Random\Randomizer (PHP 8.2+) is an object that turns the output of a random engine into useful values: integers, floats, bytes, shuffled arrays and picked keys. Because each randomizer owns its engine, you can have several independent sequences, seed one for a reproducible test and leave another secure, without touching PHP's global generator.
Without an argument the randomizer uses Random\Engine\Secure, the same cryptographically secure source as random_int(). To get a repeatable sequence, pass a seeded engine such as Random\Engine\Mt19937, Random\Engine\Xoshiro256StarStar or Random\Engine\PcgOneseq128XslRr64.
<?php $r = new Random\Randomizer(); // secure $seeded = new Random\Randomizer(new Random\Engine\Mt19937(42)); echo $seeded->getInt(1, 100); // repeatable
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
new Random\Randomizer(?Random\Engine $engine = null) $r->getInt(int $min, int $max): int $r->nextInt(): int $r->getFloat(float $min, float $max, Random\IntervalBoundary $boundary = IntervalBoundary::ClosedOpen): float $r->nextFloat(): float $r->getBytes(int $length): string $r->getBytesFromString(string $string, int $length): string $r->shuffleArray(array $array): array $r->shuffleBytes(string $bytes): string $r->pickArrayKeys(array $array, int $num): array
| Name | Description |
|---|---|
$engine |
The source of randomness. null means Random\Engine\Secure. |
getInt($min, $max) |
Uniform integer in the inclusive range, like random_int(). |
nextInt() |
Next raw integer from the engine. |
getFloat() / nextFloat() |
A float in a chosen interval, or in [0, 1). Added in PHP 8.3. |
getBytes($length) |
A binary string from the engine. |
getBytesFromString($string, $length) |
A string of $length random bytes picked from $string (PHP 8.3). |
shuffleArray($array) |
Returns a shuffled copy; the keys are renumbered. |
pickArrayKeys($array, $num) |
Returns $num distinct keys, in the order they appear in the array. |
Errors: ValueError for invalid ranges or counts; Random\RandomException if an engine fails.
Usage notes
- No global state. Unlike
mt_srand(), a seeded randomizer is isolated, so libraries and tests don't disturb each other. - Engines:
Secureis unseedable and secure;Mt19937is the classic generator behindmt_rand();PcgOneseq128XslRr64andXoshiro256StarStarare fast, high-quality, seedable engines. OnlySecureis suitable for secrets. - Seeds:
Mt19937takes an integer;Xoshiro256StarStartakes an integer or a 32-byte string,PcgOneseq128XslRr64an integer or 16-byte string. - Own engines: implement
Random\Engineto plug in anything that returns random bytes. - Stable sequences: a seeded engine yields the same numbers on the same PHP version, but the shuffling algorithm is not guaranteed across releases.
- Randomizers can be serialized and cloned when the engine supports it, which lets you save and resume a sequence.
- Dependency injection: accept a
Randomizerin constructors so tests can pass a seeded one.