README

Kontrolio: 管控你的数据。

Kontrolio 是一个简单独立的数据验证库，受 Laravel 和 Symfony 启发，并兼容 PHP 8.1+。[ 继续阅读 Medium ]

设置验证器

设置验证器的最佳方式

// In container unaware environments
$valid = Factory::getInstance()->make($data, $rules, $messages)->validate();

// Using a service container implementation
$container->singleton('validation', static fn() => new Factory());
$container->get('validation')->make($data, $rules, $messages)->validate();

当然，您可以直接使用 Kontrolio\Validator 类，但那时您需要自己提供可用的验证规则

$validator = new Validator($data, $rules, $messages)->extend($custom)->validate();

这里的数据应该是键值对——属性及其值

$data = [
    'foo' => 'bar',
    'bar' => 'baz',
    'baz' => 'taz'
];

验证规则可以设置在三种不同的格式中

类似 Laravel 的字符串
基于类的规则的实例
可调用者（闭包或回调函数）

当您为单个属性设置多个验证规则时，您可以混合实例和可调用者。以下是一个简单的示例

$rules = [
    'one' => 'not_empty|length:5,15',
    'two' => new Email,
    'three' => static fn ($value) => $value === 'taz',
    'four' => [
        static fn ($value) => is_numeric($value),
        new GreaterThan(5),
    ]
];

当您以字符串形式设置验证规则时，验证器将解析它为一个普通的规则数组，然后在将其应用于属性之前应用它们，因此当您写入 'some' => 'not_empty|length:5,15' 时，它变为

'some' => [
    new NotEmpty,
    new Length(5, 15)
]

这很简单，但请记住，所有在分号（由逗号分隔）之后传递的参数都成为验证规则构造函数的参数。

当您设置回调作为验证规则时，它内部被特殊对象 Kontrolio\Rules\CallbackRuleWrapper 包装，以保持由 Kontrolio\Rules\RuleInterface 接口定义的一致性。

规则选项

允许空值

当验证的属性值为空时，可以跳过单个规则的验证。如果您觉得需要此选项，请使用命名构造函数 allowingEmptyValue() 或通过调用 allowEmptyValue() 方法在现有实例上创建一个规则

'some' => [
    MyRule::allowingEmptyValue(),
    // (new MyRule())->allowEmptyValue()
]

跳过规则验证

当创建基于类的自定义规则时，您可能需要根据某些条件跳过其验证。您可以使用 canSkipValidation() 方法定义行为

class MyRule extends AbstractRule
{
    public function canSkipValidation($input = null)
    {
        return $input === 'bar';
    }

    // ...
}

可调用规则

可调用规则不过是闭包或函数，它接受一个属性值并返回验证结果的布尔值或与基于类的验证规则提供的选项数组等效的选项数组

    'foo' => static fn ($value) => is_string($value),
    'bar' => static function ($value) {
        return [
            // required when array
            'valid' => $value === 'taz',
            
            // optionals
            'name' => 'baz', // rule identifier
            'empty_allowed' => true, // allowing empty value
            'skip' => false // don't allow skipping current rule validation,
            'violations' => [] // rule violations
        ];
    }

自定义规则

当然，您可以创建自定义规则。只需记住，每个规则都必须是 Kontrolio\Rules\RuleInterface 的实例，实现 isValid() 方法，并有一个标识符。默认情况下，标识符由 Kontrolio\Rules\AbstractRule 解析，基于没有命名空间的规则类名。但是，如果您希望，可以覆盖此行为，通过覆盖 getName() 方法。

可以通过工厂或验证器本身添加自定义规则

$factory = (new Factory())->extend([CustomRule::class]);

// with a custom identifier
$factory = (new Factory())->extend(['some_custom' => CustomRule::class]);
$validator = $factory->make([], [], []);

// if you don't use factory
$validator = new Validator([], [], []);
$validator->extend([CustomRule::class]);

// with a custom identifier
$validator->extend(['custom' => CustomRule::class]);
$validator->validate();

完全绕过属性值的验证

这不同于在规则上使用 allowEmptyValue() 或 canSkipValidation()。使用这些您只能跳过 一个规则。但您还可以使用 Kontrolio\Rules\Core\Sometimes 规则绕过整个属性。 Sometimes 告诉验证器在属性值为 null 或空时绕过验证。就是这样。您可以在属性的规则数组中添加 Sometimes 或在规则集字符串中使用其标识符

$rules = [
    'one' => 'sometimes|length:5,15',
    // 'one' => [
    //     new Sometimes(),
    //     new Length(5, 15)
    // ]
];

在第一次失败时停止验证

您可以让验证器在发生任何验证错误时停止验证

$validator->shouldStopOnFailure()->validate();

在第一次失败时停止某些属性的验证

使用UntilFirstFailure验证规则，您也可以在保持整体验证的同时停止单个属性的验证

$data = [
    'attr' => '',
    'attr2' => 'value2'
];

$rules = [
    'attr' => [
        new UntilFirstFailure(),
        new NotBlank(),
        new NotFooBar()
    ]
];

$messages = [<...>];

$validator = new Validator($data, $rules, $messages)->validate();

现在当attr使用NotBlank规则失败时，其验证将被停止，验证器将进行到attr2。

错误信息和规则违规

错误信息具有单一的简单格式，您会喜欢的

$messages = [
    'foo' => 'Foo cannot be null',
    'foo.length' => 'Wrong length of foo',
    'foo.length.min' => 'Foo is less than 3'
    // '[attribute].[rule].[violation]
];

每个消息密钥都可以有三个部分，由点分隔。它们是

属性名称
验证规则标识符
验证规则违规

使用这些选项，您可以从最一般到最具体的程度自定义消息。每个违规都由验证属性值的规则设置。因此，在编写您自己的验证规则时，您可能需要提供自己的违规来提供验证结果和错误消息的可定制性。

franzose / kontrolio

维护者

详细信息