README

Random by Valorin

Random 通过 PHP 的简单辅助包生成各种格式的加密安全随机值。

由于我在进行Laravel 和 PHP 安全审计时，不断遇到应用程序中弱而不安全的随机值生成，所以我创建了一个安全的解决方案，可以指向我的客户，而无需他们自己实现安全算法。然后，这个想法进一步扩展，以支持我遇到的所有常见随机值类型。

Random 完全不受框架的限制，唯一的依赖项是优秀的 php-random-polyfill，在 PHP 8.2+ 中，这些函数已包含在核心中。它支持 Laravel 的 Collections，但不会引入任何 Laravel 代码。

您可以在 Securing Laravel In Depth 文章 中了解更多关于 Random 的信息。

安装

您可以通过 composer 安装此包

composer require valorin/random

无需安装任何服务提供者，Random 应该直接使用。

Random 支持 PHP 7.1 及以上版本。

用法

Random 被设计得尽可能简单易用。它是一个静态类，因此您可以直接调用方法。

将类导入您的命名空间

use Valorin\Random\Random;

随机整数

生成一个介于 $min 和 $max 之间的随机整数（包含）

$number = Random::number(int $min, int $max): int;

请注意，这仅在您使用特定的 随机化引擎（例如使用种子时）真正有用。对于大多数用例，我建议使用 random_int() 以保持简单。

随机一次性密码（数字固定长度 OTP）

生成一个长度为 $length 位的随机数字一次性密码（OTP）

$otp = Random::otp(int $length): string;

这对于生成用于短信或电子邮件验证码的一次性密码很有用。这些通常使用 rand(100000, 999999) 来完成，这不仅不安全，而且还会丢失 0-99999 范围内 10% 的可能代码。这提供了一个安全的替代方案，它包括了 000000-999999 的完整范围（具有可变长度）。

随机字符串

生成一个包含从启用字符类型中选择的 $length 个字符的随机字符串。默认情况下，它将随机选择字符，并保证不包含任何特定的字符类型。如果您需要包含每种字符类型中的一个，可以设置 $requireAll = true。

// Primary method
$string = Random::string(
    int $length = 32,
    bool $lower = true,
    bool $upper = true,
    bool $numbers = true,
    bool $symbols = true,
    bool $requireAll = false
): string;

以下是一些常见用例的包装器

// Random letters only
$letters = Random::letters(int $length = 32): string;

// Random alphanumeric (letters and numbers) token string
$token = Random::token(int $length = 32): string;

// Random letters, numbers, and symbols (i.e. a random password).
$password = Random::password(int $length = 16, bool $requireAll = false): string;

// Random alphanumeric token string with chunks separated by dashes, making it easy to read and type.
$password = Random::dashed(int $length = 25, string $delimiter = '-', int $chunkLength = 5, bool $mixedCase = true): string;

要限制任何类型中可用的字符（例如，小写字母、大写字母、数字或符号），您可以使用包含您自定义字符集的 Generator 实例

// Override just symbols
$generator = Random::useSymbols(['!', '@', '#', '$', '%', '^', '&', '*', '(', ')'])->string();

// Override everything
$generator = Random::useLower(range('a', 'f'))
    ->useUpper(range('G', 'L'))
    ->useNumbers(range(2, 6))
    ->useSymbols(['!', '@', '#', '$', '%', '^', '&', '*', '(', ')']);

$string = $generator->string(
    $length = 32,
    $lower = true,
    $upper = true,
    $numbers = true,
    $symbols = true,
    $requireAll = true
);

注意，您可以按任何顺序链式调用 use*() 方法，并且它们将仅在 Generator 中持续。

打乱数组、字符串或集合

安全地洗牌数组、字符串或Laravel集合，可选地保留键。

$shuffled = Random::shuffle(
    array|string|\Illuminate\Support\Collection $values,
    bool $preserveKeys = false
): array|string|\Illuminate\Support\Collection;

选择 $count 个项目或字符

从数组、字符串或Laravel集合中安全地选择 $count 个项目（或字符）。

$picks = Random::pick(
    array|string|\Illuminate\Support\Collection $values,
    int $count
): array|string|\Illuminate\Support\Collection;

传递 $count > 1 将返回与 $values 相同类型的选取结果，即数组、集合或字符字符串。

当传递 $count = 1 时，输出将是从输入中选择的单个数组/集合项目或字符。您还可以使用别名 pickOne() 从 $values 中选择单个项目。

$pick = Random::pickOne(
    array|string|\Illuminate\Support\Collection $values
): array|string|\Illuminate\Support\Collection;

使用特定的 \Random\Engine

默认情况下，Random 将使用PHP定义的安全默认 \Random\Engine。要使用不同的引擎，将其传递给 use() 方法，并在返回的 Generator 类上调用上述方法。

$generator = Random::use(\Random\Engine $engine): \Valorin\Random\Generator;

use() 的主要用途是当您需要指定特定的随机种子，以控制输出。只有返回的 \Valorin\Random\Generator 对象将使用提供的引擎（和种子），允许您独立于应用中其他对 Random 的使用创建和使用生成器。

$generator = Random::use(new \Random\Engine\Mt19937(3791));

$number = $generator->number(1, 1000);
$password = $generator->password();

您可以使用 use() 与字符集助手（useLower()、useUpper()、useNumbers()、useSymbols()）一起使用，但您需要先调用 use() 定义引擎，然后再在 Generator 对象上自定义字符集。

待办事项

[ ] 在 shuffle() 中使用 pickArrayKeys() 以获得更好的选择 [ ] pick() 应始终返回数组/集合，而 pickOne() 返回单个值 [ ] 使用 $collection->slice(0, 0)->push(...$items); 替换集合项目

支持我的工作！ ❤️

您可以在 GitHub Sponsors 上支持我的工作，或通过成为 Securing Laravel 的付费订阅者来支持，Securing Laravel 是Laravel和PHP开发者的必备安全资源！

贡献

非常欢迎贡献！虽然没有正式的指南，但请提交问题或PR，我们将从那里开始。

安全漏洞

请通过 GitHub项目 或直接联系 Stephen Rees-Carter 报告任何安全漏洞。

许可

Random 是开源软件，使用 MIT 许可证授权。