Skip to content
Tutorials Center
My learning

Topics

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
<?php
$r = new Random\Randomizer();                     // secure
$seeded = new Random\Randomizer(new Random\Engine\Mt19937(42));
echo $seeded->getInt(1, 100);                     // repeatable

Try it

PHP Seeded engines give repeatable results

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 Shuffle, pick and generate

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
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: Secure is unseedable and secure; Mt19937 is the classic generator behind mt_rand(); PcgOneseq128XslRr64 and Xoshiro256StarStar are fast, high-quality, seedable engines. Only Secure is suitable for secrets.
  • Seeds: Mt19937 takes an integer; Xoshiro256StarStar takes an integer or a 32-byte string, PcgOneseq128XslRr64 an integer or 16-byte string.
  • Own engines: implement Random\Engine to 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 Randomizer in constructors so tests can pass a seeded one.