Random\Engine::generate

Generates randomness

Description

public string Random\Engine::generate()

Returns randomness and advances the algorithm’s state by one step.

The randomness is represented by a binary string containing random bytes. This representation allows to unambiguously interpret the random bits generated by the algorithm, for example to accomodate different output sizes used by different algorithms.

Algorithms that natively operate on integer values should return the integer in little-endian byte order, for example by leveraging the pack function with the P format code. The high-level interface provided by the Random\Randomizer will interpret the returned random bytes as unsigned little-endian integers if a numeric representation is required.

It is strongly recommended that each bit of the returned string is uniformly and independently selected, as some applications require randomness based on the bit-level to work correctly. For example linear congruential generators often generate lower-quality randomness for the less significant bits of the return integer value and thus would not be appropriate for applications that require bit-level randomness.

Parameters

This function has no parameters.

Return Values

A non-empty string containing random bytes.

Note: The Random\Randomizer works with unsigned 64 bit integers internally. If the returned string contains more than 64 bit (8 byte) of randomness the exceeding bytes will be ignored. Other applications may be able to process more than 64 bit at once.

Errors/Exceptions

If generating randomness fails, a Random\RandomException should be thrown. Any other Exception thrown during generation should be caught and wrapped into a Random\RandomException.
If the returned string is empty, a Random\BrokenRandomEngineError will be thrown by the Random\Randomizer.
If the implemented algorithm is severely biased, a Random\BrokenRandomEngineError may be thrown by the Random\Randomizer to prevent infinite loops if rejection sampling is required to return unbiased results.

Examples

Example #1 Random\Engine::generate example

<?php
/**
 * Implements a Linear Congruential Generator with modulus 65536,
 * multiplier 61 and increment 17 returning an 8 Bit integer.
 *
 * Note: This engine is suitable for demonstration purposes only.
 *       Linear Congruential Generators generally generate low
 *       quality randomness and this specific implementation has
 *       a very short 16 Bit period that is unsuitable for
 *       almost any real-world use case.
 */
final class LinearCongruentialGenerator implements \Random\Engine
{
    private int $state;

    public function __construct(?int $seed = null)
    {
        if ($seed === null) {
            $seed = random_int(0, 0xffff);
        }

        $this->state = $seed & 0xffff;
    }

    public function generate(): string
    {
        $this->state = (61 * $this->state + 17) & 0xffff;

        return pack('C', $this->state >> 8);
    }
}

$r = new \Random\Randomizer(
    new LinearCongruentialGenerator(seed: 1)
);

echo "Lucky Number: ", $r->getInt(0, 99), "\n";
?>

The above example will output:

Lucky Number: 4