README

此库最初是利用Arteri Africa的资源构建的。

简介

SecureRandom 是一个用于生成随机值的库。使用 SecureRandom，您可以生成以下类型的值

原始字节
浮点数
整数
十六进制字符串
字母数字字符串（混合大小写）
通用唯一标识符（版本 4）

SecureRandom 生成的所有值都来自加密安全源。SecureRandom 生成的整数和浮点数来自 PHP 的 random_int() 函数。所有其他类型都来自 random_bytes() 函数。根据 PHP 文档，这些函数适用于加密使用，因为它们生成的值来自加密安全伪随机数生成器（CSPRNG）。这些函数生成的值的随机性相应地也适用于 SecureRandom 生成的值。

SecureRandom 可用于以下用途

一次性密码
临时/默认密码
双因素认证（2FA）码
API密钥
密码盐
文件名

以上列表并不全面。您可以使用 SecureRandom 进行更多操作。

用法

要使用 SecureRandom，请使用以下 composer 命令将依赖添加到您的项目中。

composer require meshachviktor/secure-random

然后按照以下示例将库导入到您的项目中。

use Meshachviktor\SecureRandom\SecureRandom;

生成随机字节

您可以通过调用库中的 bytes() 方法来使用库生成随机字节。

SecureRandom::bytes(int $length) :string

此方法接受一个名为 $length 的可选整数参数。默认情况下 $length 的值为 64，但可以是 1 到 64（含）之间的任何数字。如果提供小于 1 或大于 64 的值，则方法会抛出 \RangeException。由于许多原因，bytes() 方法限制返回的最大字节数为 64。如果您需要超过 64 字节，请改用 PHP 内置的 random_bytes()。

示例

$bytes = SecureRandom::bytes();    // Returns 64 bytes.
$bytes = SecureRandom::bytes(1);   // Returns 1 byte.
$bytes = SecureRandom::bytes(32);  // Returns 32 bytes.
$bytes = SecureRandom::bytes(0);   // Throws \RangeException
$bytes = SecureRandom::bytes(65);  // Throws \RangeException

生成随机浮点数

库提供了一些用于生成随机浮点数的方法。所有生成的浮点数的分数部分都限制在最多 14 位十进制数字。所有这些方法返回的数字都小于 1。负值在 -0.99999999999999 到 -0.1 的范围内，而正值在 0.1 到 0.99999999999999 的范围内。

SecureRandom::float(int $fractional_digits = 14) :float

float() 方法返回一个随机正数或负浮点数。此方法接受一个名为 $fractional_digits 的可选整数参数，默认值为 14。$fractional_digits 的值确定生成的浮点数小数点后出现多少位数字。提供小于 1 或大于 14 的值会导致方法抛出 \RangeException。

示例

$float = SecureRandom::float();    // 0.13456788654122
$float = SecureRandom::float(2);   // 0.41
$float = SecureRandom::float(10);  // -0.5774096379
$float = SecureRandom::float(0);   // Throws \RangeException
$float = SecureRandom::float(15);  // Throws \RangeException

SecureRandom::positiveFloat(int $fractional_digits = 14) :float

positiveFloat() 方法返回一个随机正浮点数。此方法接受一个名为 $fractional_digits 的可选整数参数，默认值为 14。$fractional_digits 的值确定生成的浮点数小数点后出现多少位数字。提供小于 1 或大于 14 的值会导致方法抛出 \RangeException。

示例

$float = SecureRandom::positiveFloat();    // 0.92120198810972
$float = SecureRandom::positiveFloat(2);   // 0.12
$float = SecureRandom::positiveFloat(10);  // 0.7222526563
$float = SecureRandom::positiveFloat(0);   // Throws \RangeException 
$float = SecureRandom::positiveFloat(15);  // Throws \RangeException

SecureRandom::negativeFloat(int $fractional_digits = 14) :float

negativeFloat() 方法返回一个随机负浮点数。该方法接受一个可选的整数参数 $fractional_digits，其默认值为 14。$fractional_digits 的值决定了生成的浮点数小数点后的位数。如果提供的值小于 1 或大于 14，则该方法将抛出 \RangeException。

示例

$float = SecureRandom::negativeFloat();    // -0.13456788654122
$float = SecureRandom::negativeFloat(2);   // -0.41
$float = SecureRandom::negativeFloat(10);  // -0.5774096379
$float = SecureRandom::negativeFloat(0);   // Throws \RangeException
$float = SecureRandom::negativeFloat(15);  // Throws \RangeException

SecureRandom::floatBetween(float $min, float $max) :float

floatBetween() 方法接受两个浮点参数 $min 和 $max，并返回介于 $min 和 $max（含）之间的浮点数。该方法只接受正浮点值，因此只返回正值。如果 $min 或 $max 的值超出了 0.1 和 0.99999999999999 的范围，该方法将抛出 \RangeException。如果 $min 的值大于 $max 的值，该方法还将抛出 Meshachviktor\SecureRandom\Exception\ValueException。

示例

$float = SecureRandom::floatBetween(0.1, 0.2);                        // 0.16708918081238
$float = SecureRandom::floatBetween(0.7777, 0.8888);                  // 0.8713798653067
$float = SecureRandom::floatBetween(0.25555555, 0.9999999999999999);  // Throws \RangeException
$float = SecureRandom::floatBetween(0.3, 0.2);                        // Throws ValueException

重要提示

由于四舍五入的影响，由生成浮点数的方法返回的值的分数部分有时会小于 $fractional_digits 的值。

生成随机整数

该库提供了一些生成随机整数的函数。这些函数返回的值介于 PHP_INT_MIN 和 PHP_INT_MAX（含）之间。

SecureRandom::integer() :int

integer() 方法不接受任何参数，并返回介于 PHP_INT_MIN 和 PHP_INT_MAX 之间的值。

示例

$integer = SecureRandom::integer();    // 3733559955175437818
$integer = SecureRandom::integer();    // -8615169409373723479
$integer = SecureRandom::integer();    // 898224759918621175
$integer = SecureRandom::integer();    // -4550407951101420676

SecureRandom::positiveInteger(int $length = 19) :int

positiveInteger() 方法返回一个随机正整数。该方法接受一个整数参数 $length，其默认值为 19。如果提供的值小于 1 或大于 19，则该方法将抛出 \RangeException。该方法返回的整数位数总数等于 $length 的值。

示例

$integer = SecureRandom::positiveInteger();    // 2562604524331120248 (19 digits long by default)
$integer = SecureRandom::positiveInteger(6);   // 197955 (6 digits long)
$integer = SecureRandom::positiveInteger(1);   // 7 (1 digit long)
$integer = SecureRandom::positiveInteger(0);   // Throws \RangeException
$integer = SecureRandom::positiveInteger(20);  // Throws \RangeException

SecureRandom::negativeInteger(int $length = 19) :int

negativeInteger() 方法返回一个随机负整数。该方法接受一个整数参数 $length，其默认值为 19。如果提供的值小于 1 或大于 19，则该方法将抛出 \RangeException。该方法返回的负整数位数总数等于 $length 的值。

示例

$integer = SecureRandom::negativeInteger();    // -4259319387199823755 (19 digits long by default)
$integer = SecureRandom::negativeInteger(6);   // -808209 (6 digits long)
$integer = SecureRandom::negativeInteger(1);   // -5 (1 digit long)
$integer = SecureRandom::negativeInteger(0);   // Throws \RangeException
$integer = SecureRandom::negativeInteger(20);  // Throws \RangeException

SecureRandom::integerBetween(int $min, int $max) :int

integerBetween() 方法接受两个整数参数 $min 和 $max，并返回介于 $min 和 $max（含）之间的整数。如果 $min 的值大于 $max 的值，该方法将抛出 Meshachviktor\SecureRandom\Exception\ValueException。

示例

$integer = SecureRandom::integerBetween(1, 10);        // 2
$integer = SecureRandom::integerBetween(1000, 5000);   // 4124`  
$integer = SecureRandom::integerBetween(-300, -100);   // -149
$integer = SecureRandom::integerBetween(-100, -300);   // Throws ValueException

生成随机字符串

该库提供了一些生成随机字符串的函数。可以生成三种类型的字符串。

十六进制字符串。
大小写混合的字母数字字符串
版本 4 UUIDs

当生成十六进制字符串和字母数字字符串时，相应的函数接受一个单个整数参数 $length，它决定了生成的字符串的长度。默认值为 64。如果 $length 的值小于 1 或大于 64，则抛出 \RangeException。
生成 UUID 的方法不接受任何参数。

SecureRandom::hexadecimalString(int $length = 64) :string

生成指定长度的十六进制字符串。

示例

$string = SecureRandom::hexadecimalString(8);     // 5bc3aac3
$string = SecureRandom::hexadecimalString(16);    // 6bc28f1fc391c386
$string = SecureRandom::hexadecimalString(0);     // Throws \RangeException
$string = SecureRandom::hexadecimalString(65);    // Throws \RangeException

SecureRandom::alphanumericString(int $length = 64) :string

生成指定长度的字母数字字符串。

示例

$string = SecureRandom::alphanumericString(8);     // fxbjwCmi
$string = SecureRandom::alphanumericString(16);    // 84XxE8OY7CKQg0na
$string = SecureRandom::alphanumericString(0);     // Throws \RangeException
$string = SecureRandom::alphanumericString(65);    // Throws \RangeException

SecureRandom::uuid() : string

生成版本 4 UUIDs。

示例

$uuid = SecureRandom::uuid();     // 105f4516-e80c-4c32-b2fe-42dafa85d9cd
$uuid = SecureRandom::uuid();     // 54ef56c9-cae6-48c2-824f-6d8a2737a3d6

许可证

MIT

meshachviktor / secure-random

维护者

详细信息