README

This set of classes provides basic abstraction around different pseudo random generators with the same generic API. Also it contains many useful helper methods like weighted random, text generation, shuffling, array functions, etc.

WARNING: This PRNGs are non cryptographically secure (mt_rand() too)

Why not mt_rand()?

PHP builtin mt_rand() and rand() are global functions, so it is not possible to create several generators with different predefined seeds and use them simultaneously. There is also no control over current state of random sequences.

Features

Deterministic random generators with optional seeds
Correct uniform distribution
Gaussian sampler for normally distributed random numbers based on Ziggurat algorithm
Extensible architecture: it is easy to add your own source of randomness
Seeds can be strings of any length you want
Possibility to save and restore current PRNG's state at any time, so one can replay the sequence from known state
Different random types: int, float, boolean
Weighted random: random array key by weights, weighted shuffle
Random binary data generation
Random text generation from specified characters list with optional multi-byte support
Array methods, alternatives to array_rand, shuffle

PRNG sources

XorShiftRand Fast and good quality random generator, based on XorShift+ algorithm with 128bit state. Should be used in most cases.
MtRand Pure PHP implementation of builtin mt_rand variation of Mersenne twister algorithm. Random sequences from both methods with same int seed will match perfectly, therefore this generator is fully compatible with mt_rand() and can be used as replacement.
HashRand Proof-of-concept that md5 hash is uniformly distributed and can be used as source for pseudo random numbers. Pretty fast and straightforward.

Examples

//////// BASIC USAGE ////////

// Create xorshift random generator with default random seed
$rnd = new XorShiftRand();

// Default random value between 0 and GeneratorClass::INT_MAX
$value = $rnd->random();

// Random value within given range (inclusive)
$value = $rnd->random(15, 12333);

// Negative numbers allowed
$value = $rnd->random(-128, 128);

// Random unsigned int, size depends on underlying generator
$int = $rnd->randomInt();

// Random float in range 0 <= $val <= 1
$float = $rnd->randomFloat();

// True or false
$bool = $rnd->randomBool();

//////// STATE CONTROL ////////

// Read current seed
$seed = $rnd->getSeed();

// Set new seed, generator will be reinitialized
$rnd->setSeed('some new seed');

// .... several generator calls later ...

// Save state for future use
$state = $rnd->getState();

// .... several generator calls later ...

// Set saved state and restore generator to known state
$state = $rnd->setState($state); 

// .... same calls to random methods as before will produce exactly the same output

// Reset generator to initial state with current seed ('some new seed')
$rnd->reset();

//////// STRING METHODS ////////

// Generate string with 256 random bytes
$bytes = $rnd->randomData(256);

// Generate random string from default (ALNUM) characters list with length = 17
$str = $rnd->randomString(17);

// Generate random string from numbers (0-9) with length = 99
$str = $rnd->randomString(99, $rnd::CL_NUM);

// Generate lowercase hex string with length = 32
$str = $rnd->randomString(32, $rnd::CL_HEXLC);

// Generate string from custom characters list
$str = $rnd->randomString(16, 'ABCDefgh#$%^');

// If custom list contains multi-byte characters, $mb flag must be set
$str = $rnd->randomString(16, 'АБВГДЕЁЖЗ', true);

//////// ARRAY METHODS ////////

// Get random key from array (0, 1, 2 or 'four')
$key = $rnd->arrayRand([10, 20, 30, 'four' => 40]);

// Get random value from array (10, 20, 30 or 4)
$value = $rnd->arrayRandValue([10, 20, 30, 'four' => 40]);

// Shuffle array. New numeric keys will be assigned
$array = [1, 2, 'key' => 3, 4, 'assoc' => 5, 6, 7];
$rnd->arrayShuffle($array);

// Shuffle array and maintain key => value associations
$array = [1, 2, 'key' => 3, 4, 'assoc' => 5, 6, 7];
$rnd->arrayShuffleAssoc($array);

//////// WEIGHTED RANDOM ////////

// Array in "key => weight" form must be specified
$array = ['one' => 1, 'two' => 2, 'three' => 3, 'four' => 4, 'four2' => 4];

// Get random key from array by weights. 
// So 'one' will appear less likely than 'four'\'four2'
$key = $rnd->arrayWeightRand($array);

// Shuffle array using weights. 
// So 'four'\'four2' likely will appear earlier than 'one' in resulting array
$rnd->arrayWeightShuffle($array);

More info

PRNG: https://en.wikipedia.org/wiki/Pseudorandom_number_generator
XorShift: https://en.wikipedia.org/wiki/Xorshift
Mersenne Twister: https://en.wikipedia.org/wiki/Mersenne_Twister
Some PRNGs benchmark: http://xorshift.di.unimi.it/
Normal distribution: https://en.wikipedia.org/wiki/Normal_distribution
Ziggurat algorithm: https://en.wikipedia.org/wiki/Ziggurat_algorithm

savvot / random

Maintainers

Details