README

PASVL - PHP 数组结构验证库

想象一下正则表达式 [ab]+ 匹配字符串 abab。现在想象一下对数组做同样的事情。

该库的目的是验证现有（嵌套）数组与模板的匹配，并报告不匹配。它具有面向对象的可扩展架构，可以编写和添加自定义验证器。

注意当前用户：此版本与之前的 0.5.6 不兼容。

安装

composer require lezhnev74/pasvl

示例

请参考 Example 文件夹中的文件。

用法

数组验证

// Define the pattern of the data, define keys and values separately
$pattern = [
    '*' => [
        'type' => 'book',
        'title' => ':string :contains("book")',
        'chapters' => [
            ':string :len(2) {1,3}' => [
                'title' => ':string',
                ':exact("interesting") ?' => ':bool',
            ],
        ],
    ],
];

// Provide the data to match against the above pattern.
$data = [
    [
        'type' => 'book',
        'title' => 'Geography book',
        'chapters' => [
            'eu' => ['title' => 'Europe', 'interesting' => true],
            'as' => ['title' => 'America', 'interesting' => false],
        ],
    ],
    [
        'type' => 'book',
        'title' => 'Foreign languages book',
        'chapters' => [
            'de' => ['title' => 'Deutsch'],
        ],
    ],
];

$builder = \PASVL\Validation\ValidatorBuilder::forArray($pattern);
$validator = $builder->build();
try {
    $validator->validate($data);
} catch (ArrayFailedValidation $e) {
    // If data cannot be matched against the pattern, then exception is thrown.
    // It is not always easy to detect why the data failed matching, the exception MAY sometimes give you extra hints.
    echo "failed: " . $e->getMessage() . "\n";
}

可选字符串验证

$pattern = ":string :regexp('#^[ab]+$#')";
$builder = \PASVL\Validation\ValidatorBuilder::forString($pattern);
$validator = $builder->build();
$validator->validate("abab"); // the string is valid
$validator->validate("abc"); // throws RuleFailed exception with the message: "string does not match regular expression ^[ab]+$"

验证语言

此包支持用于验证规范的专用方言。它看起来像这样

简短的语言参考

规则名称 指定零个或一个规则名称应用于数据。可选后缀 ? 允许数据为 null。请参阅 src/Validation/Rules/Library 中的内置规则集。有关自定义规则，请参阅下面的 自定义规则。例如，:string? 描述字符串和 null。
子规则名称 指定零个或多个子规则名称在应用规则后应用于数据。子规则是主规则的额外方法。例如，:number :float 描述浮点数。
限定符 指定数据键的期望数量。如果没有设置，则假定默认值 - !。可用的限定符
- ! - 一个键（默认）
- ? - 可选键
- * - 任何数量的键
- {2} - 严格键数
- {2,4} - 键数的范围
例如
```
  $pattern = [":string *" => ":number"];
  // the above pattern matches data:
  $data = ["june"=>10, "aug" => "11"];
```

模式定义

作为精确值

$pattern = ["name" => ":any"]; // here the key is the exact value
$pattern = ["name?" => ":any"]; // here the key is the exact value, can be absent as well
$pattern = [":exact('name')" => ":any"]; // this is the same

作为可空规则

$pattern = ["name" => ":string?"]; // the value must be a string or null

作为带有子规则的规则

$pattern = ["name" => ":string :regexp('#\d*#')"]; // the value must be a string which contains only digits

作为带有限定符的规则

$pattern = [":string {2}" => ":any"]; // data must have exactly two string keys

复合定义

此包支持以自然语言表达规则组合。例如

:string 或 :number
:string 和 :number
(:string 和 :number) 或 :array

有两种组合运算符：and 和 or。 and 运算符具有优先级。两者都是左结合的。

自定义规则

默认情况下，系统仅使用内置规则。但是，您可以使用自己的实现来扩展它们。要添加新的自定义规则，请按照以下步骤操作

将您的新规则作为类实现，并从 \PASVL\Validation\Rules\Rule 扩展
通过扩展类 \PASVL\Validation\Rules\RuleLocator 实现新的规则定位器

按照这种方式配置验证器

$builder = ValidatorBuilder::forArray($pattern)->withLocator(new MyLocator()); // set your new locator
$validator = $builder->build();

内置规则

此包附带一些内置规则及其相应的子规则（请参阅 src/Validation/Rules/Library 文件夹）

:string - 值必须是字符串
- :regexp(<string>) - 提供一个正则表达式（与 preg_match() 相同）
- :url
- :email
- :uuid
- :contains(<string>)
- :starts(<string>)
- :ends(<string>)
- :in(<string>,<string>,...)
- :len(<int>)
- :max(<int>)
- :min(<int>)
- :between(<int>,<int>)
:number
- :max(<int>)
- :min(<int>)
- :between(<int>, <int>)
- :int - 数字必须是整数
- :float - 数字必须是浮点数
- :positive
- :negative
- :in(<a>,<b>,<c>) - 数字必须在值范围内（可以进行类型强制转换）
- :inStrict(<a>,<b>,<c>) - 数字必须在值范围内（禁用类型强制转换）
:exact(<value>)
:bool(<?value>) - 值必须是布尔值，如果提供了可选参数，值必须完全匹配
:object
- :instance(<fqcn>)
- :propertyExists(<string>)
- :methodExists(<string>)
:array
- :count(<int>)
- :keys(<string>,<string>,...)
- :min(<int>) - 最小数量
- :max(<int>) - 最大数量
- :between(<int>, <int>) - 数量必须在范围内
:any - 代替符，任何值都将匹配

提示

PHP将"1"转换为1作为数组键

$data = ["12" => ""];
$pattern_invalid = [":string" => ""];
$pattern_valid = [":number :int" => ""];

从技术上讲，PASVL是一个非确定性回溯解析器，因此它不一定能显示哪个确切键没有匹配到模式。这是因为，例如，一个键可以匹配不同的模式，而且无法确定哪个是正确的。在这种情况下，它将返回类似“在X级别没有找到匹配项”的消息。

🏆 贡献者

Greg Corrigan. Greg发现了一个关于可以为空值报告为无效的问题。
Henry Combrinck. Henry在真实数据上对库进行了广泛的测试，并发现了棘手的错误和边缘情况。对社区的宝贵贡献。
@Averor. 在括号解析中发现了错误。
Julien Gidel. 改进了regexp子规则。

许可

本项目受MIT许可条款的约束。

lezhnev74 / pasvl

维护者

详细信息