README

只是一个随机构造库，但更酷！具有许多开箱即用功能和由 MCrypt 和/或 OpenSSL 提供的 '加密安全伪随机数生成器' (CSPRNGs) 支持。

#安装要在项目中使用 Casus，最简单的方法是通过 composer。您可以手动下载文件并使用一个兼容 psr-4 的自动加载器来自动加载 src 目录中的文件，但这不是推荐的，并且被强烈反对。

通过 composer.json 文件

在您的 composer.json 文件中添加此行，并在命令行上运行 composer install

"require": {
    "hedronium/casus": "*"
}

通过命令行

只需在您的项目目录中运行即可

composer require hedronium/casus

#使用基本上您只需要实例化 Casus 类的对象，然后您就可以开始了！

<?php
//Include the Composer Autoloader
include "vendor/autoload.php";

$casus = new \hedronium\Casus\Casus();
echo $casus->integer();

上述示例将输出一个介于 0 和 PHP_INT_MAX 之间的数字，该数字对应于您的 PHP 安装。

实际上，casus 类将所有方法调用转发到生成器实例，因此如果您愿意，可以获取生成器实例并直接调用其方法。例如

<?php
$casus = new \hedronium\Casus\Casus();
$random_generator = $casus->getGenerator();
echo $random_generator->integer();

#方法

方法列表

整数 - 生成一个随机整数
浮点数 - 生成一个随机浮点数
布尔值 - 生成一个随机布尔值
字母 - 生成一个包含字母的随机字符串
字母数字 - 生成一个包含字母和数字的随机字符串
ASCII 范围 - 从 ASCII 表中的范围生成一个随机字符串
字符串 - 从字符集中生成一个随机字符串
整数数组 - 生成一个随机整数数组
唯一整数数组 - 生成一个唯一随机整数数组
浮点数数组 - 生成一个随机浮点数数组
随机化 - 随机化数组或字符串的顺序
随机选择 - 从数组中随机选择元素
字节 - 生成一个随机字节
字节字符串 - 生成一个随机字节字符串

每个方法上的 $secure 参数用于暂时覆盖安全实例中的安全生成器，以使用非安全生成器。（这可以通过将其设置为 false 来完成）。默认情况下，它设置为 true。

integer ($min, $max [, $secure])

返回一个介于 $min 和 $max 之间的数字

参数

int $min (0)

返回数字的下限
int $max (PHP_INT_MAX)

返回数字的上限

float ($min, $max, $precision [, $secure])

返回一个在 $min 与 $max 之间的浮点数

参数

int $min (0)

返回数字的下限
int $max (PHP_INT_MAX)

返回数字的上限
int $precision (4)

小数位数

boolean ([$secure])

返回一个布尔值（true 或 false）

alpha ($length, $case_randomization [, $secure])

返回由字母组成的字符串

参数

int $length (32)

随机字符串的长度
boolean $case_randomization (true)

是否随机大小写

alphanum ($length, $case_randomization [, $secure])

返回由字母和数字组成的字符串

参数

int $length (32)

随机字符串的长度
boolean $case_randomization (true)2nd parameter)

是否随机大小写

asciiRange ($length, $ranges [, $secure])

返回由 ASCII 字符组成，范围由 $ranges 定义的字符串

参数

int $length (32)

随机字符串的长度
array $ranges ([[65,90],[97,122],[48,57]])
ASCII 表中字符编码的取值范围。它可以是单维数组，第一个值是起始点，第二个值是结束点。
例如：asciiRange(32, [97, 122]) [A-Z]

或者

它也可以是多维数组，定义一组范围，如下所示：
```
$ranges = [
  [65,90],
  [97,122],
  [48,57]
];

asciiRange(32, $ranges)
```
上面的例子生成一个包含小写字母、大写字母和数字的字符串

string ($length, $charset [, $secure])

返回由 $charset 中指定的字符组成的字符串

参数

int $length (32)

随机字符串的长度
array/string $charset (abcdefghijklmopqrstuvwxyz)

用于随机字符串的字符数组或字符串

integerArray ($min, $max, $length [, $secure])

返回一个随机整数数组

参数

int $min (0)

返回数字的下限
int $max (PHP_INT_MAX)

返回数字的上限
int $length (10)

生成的数组长度

uniqueIntegerArray ($min, $max, $length [, $secure])

返回一个唯一随机整数数组

参数

int $min (0)

返回数字的下限
int $max (PHP_INT_MAX)

返回数字的上限
int $length (10)

生成的数组长度

floatArray ($min, $max, $precision, $length [, $secure])

返回一个随机浮点数数组

参数

int $min (0)

返回数字的下限
int $max (PHP_INT_MAX)

返回数字的上限
int $precision (4)

小数位数数组或字符串
int $length (10)

生成的整数数组长度

randomize ($input [, $secure])

接受一个数组或字符串，并返回其随机版本。

参数

array/string $input

要随机化的数组或字符串

selectRandom ($input, $length [, $secure])

从数组或字符串中随机选择元素

参数

array/string $input

要从中随机选择的数组或字符串
int $length (10)

生成的数组或字符串长度

byte ([$secure])

返回一个随机字节

byteString ($length [, $secure])

返回一个随机字节字符串

参数

int $length (32)

生成的字节字符串长度

初始化选项

$secure

类型： boolean
默认： true
是否使用密码学安全的生成器。默认情况下，将使用类似于 MCrypt 或 OpenSSL 的 CSPRNG。

$casus = new Casus(false);

上面的例子让 Casus 使用一个非密码学安全的生成器。（它只是使用了 PHP 内置的 mt_rand 函数）

$generator

类型： Generator
默认： null
注入要使用的生成器实例。（必须是 \hedronium\Casus\Generator 的子类的实例）

$generator = new \hedronium\Casus\OpenSSL();
$casus = new Casus(true, $generator);

上面的例子指定了默认 OpenSSL 生成器的实例。
注意：如果提供的生成器不安全且 $secure 设置为 true，Casus 将抛出 \hedronium\Casus\errors\Insecure 异常。

#其他方法

isSecure()

返回：boolean
返回当前使用的生成器是否安全。

hasMCrypt()

返回：boolean
返回你的 PHP 安装是否启用了 MCrypt 扩展。

hasOpenSSL()

返回：boolean
返回你的 PHP 安装是否启用了 OpenSSL 扩展。

getGenerator()

返回：Generator
返回当前使用的生成器实例。

setGenerator($secure, $generator)

返回：boolean
根据参数设置新的生成器。（实际上这是构造函数在幕后调用的方法）

成功时返回 true，如果第一个参数为 true 但生成器参数不是一个安全的生成器，或者没有找到安全生成器扩展，则抛出 hedronium\Casus\errors\Insecure 异常。

##编写自定义生成器 ###创建生成器要创建一个生成器，只需编写一个扩展抽象类 \hedronium\Casus\Generator 的类即可。实现 integer ($min, $max) 方法是绝对必要的。（它已经是抽象方法，所以如果您忘记实现它，将会得到一个错误）

示例生成器

<?php
class SuperGenerator extends \hedronium\Casus\Generator
{
    public function integer($min, $max)
    {
        return rand($min, $max);
    }
}

###使用您的自定义生成器只需将其作为 Casus 构造函数的第二个参数传递

<?php
$generator = new SuperGenerator();
$casus = new \hedronium\Casus\Casus(false, $generator);

或者直接实例化您的生成器类（Casus 主类实际上没有用，它实际上只是将所有方法调用转发到生成器实例）

<?php
$random = new SuperGenerator();

注意： Casus 主类可以用来强制使用安全生成器。

###是否为加密安全？如果您的生成器是加密安全的（使用 CSPRNG 算法），则必须指定它，这样 Casus 才不会报错。

您可以通过在您的生成器类中将 $secure 属性设置为 true 来这样做

<?php
class SuperGenerator extends \hedronium\Casus\Generator
{
    protected $secure = true;
    
    public function integer($min, $max)
    {
        return rand($min, $max);
    }
}

###对您的生成器进行单元测试在 Casus 的 Tests 目录中扩展 GeneratorTest 类是对您自定义生成器进行单元测试的最简单方法。由于 CeneratorTest 类已经扩展了 PHPUnit_Framework_TestCase 类，因此您不必这样做。

尽管如此，您仍然需要实现 setUp()，以便将 casus 属性设置为 TestClass 对象的您的生成器类实例。

示例

<?php
include_once __DIR__.'/../vendor/autoload.php';
include_once __DIR__.'/GeneratorTest.php';

class SuperGeneratorTest extends \GeneratorTest
{
    public function setUp() {
        $this->casus = new \AwesomePerson\SuperGenerator();
    }
}

这将测试 Casus 包含的所有标准方法。您可以继续添加对您特殊方法的测试。

hedronium / casus

维护者

详细信息