README

这是一个端到端的PHP验证库。在任何需要验证（甚至可能清理）一组值的情况下都很有用。它包含一个可扩展的规则列表，可以轻松使用，使使用规则变得简单且声明式。

如何使用

安装

建议使用 Composer 安装此库。要这样做，请运行以下命令

composer require stellarwp/validation

如果要在WordPress中使用此库，强烈建议您使用 Strauss，以避免与其他插件冲突。

配置和初始化

库包含一个 Config 类，用于设置和初始化库。以下是如何使用它的示例

use StellarWP\Validation\Config;

Config::setServiceContainer(MyContainer::class); // required
Config::setHookPrefix('my_plugin_'); // recommended

Config::setInvalidArgumentExceptionClass(MyInvalidArgumentException::class); // optional
Config::setValidationExceptionClass(MyValidationException::class); // optional

Config::initialize(); // mounts rules registrar to service container

服务容器用于依赖注入。库使用此容器存储 ValidationRulesRegistrar，以跟踪所有可用的规则。必须设置，并实现容器接口。如果您没有容器，可以使用 StellarWP 容器或 di52 容器。

验证数据

库中的两个主要类是 Validator 和 ValidationRuleSet。Validator 类用于验证数据，而 ValidationRuleSet 用于定义验证规则。以下是如何使用 Validator 类

use StellarWP\Validation\Validator;

$values = [
    'name' => 'Bill Murray',
    'age' => 76
];

$labels = [
    'name' => 'Name',
    'age' => 'Age'
];

$validator = new Validator([
    'name' => ['required'],
    'age' => ['required', 'integer', 'min:18', 'max:150']
], $values, $labels);

if ($validator->passes()) {
    $safeData = $validator->validated();
} else {
    $errors = $validator->errors();
}

Validator 类接受三个参数

$values - 要验证的值
$rules - 用于验证的规则
$labels - 用于错误信息的标签

Validator::passes() 在所有规则通过时返回 true

Validator::fails() 在任何规则失败时返回 true

Validator::validated() 返回验证后的数据 - 没有规则的值将被删除，确保只返回可信数据。

Validator::errors() 返回错误数组。键与 $values 数组的键匹配，值是错误信息。如果没有错误，将返回空数组。

规则参数

传递给 Validator 的 $rules 参数可以是数组或规则，或 ValidationRuleSet 实例。

当传递数组时，规则可以以三种方式定义

$rules = [
    'name' => [
        // As a string
        'required',

        // As a Rule instance
        new \StellarWP\Validation\Rules\Min(1),

        // As a closure
        function ($value, Closure $fail, string $key, array $values) {
            if ($value === 'foo') {
                $fail('{field} cannot be foo');
            }
        }
    ]
];

向现有类添加规则

有时您有一个代表单个值的类，如值对象。在这种情况下，您可以使用 HasValidationRules 特性向类添加验证规则。此特性向类添加了各种用于管理规则的方法。

添加新规则

库自带了一些规则，但您可以轻松添加自己的规则。

规则如何解析

在向规则集添加规则时，您可以传递一个字符串、一个 Rule 实例或一个闭包。当传递一个字符串时，库将尝试使用 ValidationRulesRegistrar 来解析它。静态的 Rule::id() 方法用于注册规则。例如，Min 的 id 是 min。因此，当字符串规则为 min:18 时，将解析出 Min 规则。在冒号之后还可以向规则传递额外的选项。

这可能看起来有些麻烦，但当使用时，它允许编写易于阅读的声明性规则。

基本规则

为了使一个类成为规则，它必须实现 ValidationRule 接口。请参阅接口以获取关于其方法的文档。

前端兼容规则

如果一个类实现了 ValidatesOnFrontEnd 接口。

所有规则都位于 ValidationRuleSet 中。该类支持在 json_encode 函数中使用，此时它将生成一个列表，列出所有可以在前端进行验证的规则。例如，年龄验证规则将生成以下 JSON：

{
    "required": true,
    "integer": null,
    "min": 18,
    "max": 150
}

此 JSON 可以发送到前端，并适配到像 Joi 这样的库进行前端验证。这使得以下流程成为可能：

在服务器上定义您的输入规则
将规则作为 JSON 传递到浏览器
将规则转换为您的系统并在浏览器中进行验证
将结果输入数据传递到服务器
在服务器上安全地重新验证输入

前端数据不安全，但它提供了良好的用户体验。因此，在单一位置定义它，并在浏览器和服务器上以相同的方式工作，是非常优秀的。

净化规则

规则还可以提供净化功能——也就是说，它们可以在返回值之前修改值。为此，请实现 Sanitizer 接口。请注意，净化发生在验证之后，因此只有在值首先通过验证后才会进行净化。

最后，请注意，净化会影响发送到下一个规则之前的值。这在您想基于值的类型进行验证的情况下很有用。以年龄为例：

$rules = [
    'age' => ['required', 'integer', 'min:18', 'max:150']
];

integer 规则将值转换为整数。因此，min:18 将检查年龄是否数值上大于或等于 18。如果没有 integer 规则，如果 age 是字符串，那么 min:18 将计算字符数，而不是数值。

stellarwp / validation

维护者

详细信息