class SecureRandom (View source)

Library for normalizing bytes returned by secure random byte generators.

SecureRandom takes bytes generated by secure random byte generators and normalizes (i.e. provides even distribution) for other common usages, such as generation of integers, floats and randomizing arrays.

Methods

__construct(Generator $generator = null)

Creates a new instance of SecureRandom.

string
getBytes(int $count)

Returns a number of random bytes.

int
getInteger(int $min, int $max)

Returns a random integer between two positive integers (inclusive).

float
getRandom()

Returns a random float between 0 and 1 (excluding the number 1).

float
getFloat()

Returns a random float between 0 and 1 (inclusive).

array
getArray(array $array, int $count)

Returns a number of randomly selected elements from the array.

mixed
choose(array $array)

Returns one randomly selected value from the array.

array
shuffle(array $array)

Returns the array with the elements reordered in a random order.

array|string
getSequence(string|array $choices, int $length)

Returns a random sequence of values.

string
getUuid()

Returns a random UUID version 4 identifier.

Details

__construct(Generator $generator = null)

Creates a new instance of SecureRandom.

You can either provide a generator to use for generating random bytes or give null as the argument to use default generators. If null is provided, the constructor will attempt to create the random byte generators in the following order until it finds one that is supported:

  • Internal
  • RandomReader
  • Mcrypt
  • OpenSSL

Note that since most cases require non-blocking random generation, the default generators use /dev/urandom as the random source. If you do not think this provides enough security, create the desired random generator using /dev/random as the source.

Parameters

Generator $generator Random byte generator or null for default

Exceptions

GeneratorException If the provided or default generators are not supported

string getBytes(int $count)

Returns a number of random bytes.

Parameters

int $count Number of random bytes to return

Return Value

string Randomly generated bytes

Exceptions

InvalidArgumentException If the count is invalid

int getInteger(int $min, int $max)

Returns a random integer between two positive integers (inclusive).

Parameters

int $min Minimum limit
int $max Maximum limit

Return Value

int Random integer between minimum and maximum limit

Exceptions

InvalidArgumentException If the limits are invalid

float getRandom()

Returns a random float between 0 and 1 (excluding the number 1).

Return Value

float Random float between 0 and 1 (excluding 1)

float getFloat()

Returns a random float between 0 and 1 (inclusive).

Return Value

float Random float between 0 and 1 (inclusive)

array getArray(array $array, int $count)

Returns a number of randomly selected elements from the array.

This method returns randomly selected elements from the array. The number of elements is determined by by the second argument. The elements are returned in random order but the keys are preserved.

Parameters

array $array Array of elements
int $count Number of elements to return from the array

Return Value

array Randomly selected elements in random order

Exceptions

InvalidArgumentException If the count is invalid

mixed choose(array $array)

Returns one randomly selected value from the array.

Parameters

array $array The array to choose from

Return Value

mixed One randomly selected value from the array

Exceptions

InvalidArgumentException If the array is empty

array shuffle(array $array)

Returns the array with the elements reordered in a random order.

Parameters

array $array The array to shuffle

Return Value

array The provided array with elements in a random order

array|string getSequence(string|array $choices, int $length)

Returns a random sequence of values.

If a string is provided as the first argument, the method returns a string with characters selected from the provided string. The length of the returned string is determined by the second argument.

If an array is provided as the first argument, the method returns an array with elements selected from the provided array. The size of the returned array is determined by the second argument.

The functionality is similar to getArray(), except for the fact that the returned value can contain the same character or element multiple times. If the same character or element appears multiple times in the provided argument, it will increase the relative chance of it appearing in the returned value.

Parameters

string|array $choices Values to choose from
int $length Length of the sequence

Return Value

array|string The generated random sequence

Exceptions

InvalidArgumentException If the choices or length is invalid

string getUuid()

Returns a random UUID version 4 identifier.

Return Value

string A random UUID identifier