<?php

/**
 * PHP 8.2 introduces a new PHP extension named "random".
 * @see https://github.com/php/php-src/blob/master/ext/random/random.stub.php
 * @see https://php.watch/versions/8.2/ext-random
 */

namespace Random\Engine
{
    final class Mt19937 implements \Random\Engine
    {
        public function __construct(int|null $seed = null, int $mode = MT_RAND_MT19937) {}

        /** @return non-empty-string */
        public function generate(): string {}

        public function __serialize(): array {}

        public function __unserialize(array $data): void {}

        public function __debugInfo(): array {}
    }

    final class PcgOneseq128XslRr64 implements \Random\Engine
    {
        public function __construct(string|int|null $seed = null) {}

        public function generate(): string {}

        public function jump(int $advance): void {}

        public function __serialize(): array {}

        public function __unserialize(array $data): void {}

        public function __debugInfo(): array {}
    }

    final class Xoshiro256StarStar implements \Random\Engine
    {
        public function __construct(string|int|null $seed = null) {}

        public function generate(): string {}

        public function jump(): void {}

        public function jumpLong(): void {}

        public function __serialize(): array {}

        public function __unserialize(array $data): void {}

        public function __debugInfo(): array {}
    }

    final class Secure implements \Random\CryptoSafeEngine
    {
        public function generate(): string {}
    }
}

namespace Random
{
    interface Engine
    {
        public function generate(): string;
    }

    interface CryptoSafeEngine extends Engine
    {
    }

    final class Randomizer
    {
        public readonly Engine $engine;

        public function __construct(?Engine $engine = null) {}

        public function nextInt(): int {}

        public function getInt(int $min, int $max): int {}

        /**
         * @param positive-int $length
         * @return non-empty-string
         */
        public function getBytes(int $length): string {}

        /**
         * @template TValue
         * @param array<TValue> $array
         * @return list<TValue>
         */
        public function shuffleArray(array $array): array {}

        public function shuffleBytes(string $bytes): string {}

        /**
         * @template TKey as array-key
         * @param array<TKey, mixed> $array
         * @return list<TKey>
         */
        public function pickArrayKeys(array $array, int $num): array {}

        public function __serialize(): array {}

        public function __unserialize(array $data): void {}
    }

    class RandomError extends \Error
    {
    }

    class BrokenRandomEngineError extends RandomError
    {
    }

    class RandomException extends \Exception
    {
    }
}
