wscore/validator

用于验证和过滤如表单输入等值。

维护者

详细信息

github.com/WScore/Validator

源代码

问题

安装: 8

依赖项: 1

建议者: 0

安全性: 0

星星: 1

关注者: 2

分支: 0

开放问题: 5

0.3.3 2019-09-18 07:06 UTC

Requires

Requires (Dev)

MIT 7f12abb62a44f958ec879cc349cd21d4db36ee25

  • Asao Kamei <asao.kamei.woop@gmail.com>

This package is auto-updated.

Last update: 2024-09-18 18:23:20 UTC

README

验证组件，用于

  • 单个值以及数组
  • 嵌套表单输入
  • 一对多表单输入
  • 多字节支持（例如日语）

许可证

MIT 许可证

安装

t.b.w.

简单用法

验证值

创建一个 ValidationBuilder 实例，然后创建验证器；

$vb = new ValidatorBuilder();
$validator = $vb->text([
    StringLength::class => ['max' => 12],
]);
  • 创建验证，执行：$vb->{type}($option_array)。
    • type：验证类型，如后续章节中定义。
    • option_array：选项数组。StringLength 是一个过滤器（也称为验证器）。
      • multiple：布尔值。可选。用于验证多个（即数组）值。
      • type：字符串。可选。可以在选项中指定类型。
      • filters：数组。已弃用的指定过滤器的方式。
      • 所有其他选项都视为过滤器。

$result 包含验证状态和验证后的值。

$result = $validator->verify($value);
if ($result->isValid()) {
    echo $result->value(); // validated value
} else {
    var_dump($result->getErrorMessage()); // error messages
}

验证表单输入

$form = $vb->form()
    ->add('name', $vb->text([
        Required::class,
        StringCases::class => [StringCases::TO_LOWER, StringCases::UC_WORDS],
    ]))
    ->add('email', $vb->email([
        Required::class,
        StringCases::class => [StringCases::TO_LOWER],
        ConfirmWith::class => [ConfirmWith::FIELD => 'email_check'],
    ]));
$result = $form->verify([ // or simply verify $_POST here... 
    'name' => 'MY NAME',
    'email' => 'Email@Example.Com',
    'email_check' => 'Email@Example.Com',
]);

创建验证的另一种方式，执行：$vb($option_array)，其中类型可能已在 $option_array 中指定。

$result 包含表单中每个元素的子结果。

if ($result->isValid()) {
    echo $result->getChild('name')->value();  // 'My Name'
    echo $result->getChild('email')->value(); // 'email@example.com'
} else {
    // access elements in the form.
    foreach($result as $key => $element) {
        if (!$element->isValid()) {
            echo $element->getErrorMessage(); // error messages
        }
    }
}

嵌套表单

只需在表单对象中添加另一个表单对象即可。

$address = $vb->form()
    ->add('zip', $vb([
        'type' => 'digits',
        Required::class,
        StringLength::class => [StringLength::LENGTH => 5],
    ]))
    ->add('address', $vb([
        'type' => 'text',
        Required::class,
    ]))
    ->add('region', $vb([
        'type' => 'text',
        Required::class,
        InArray::class => [
            InArray::REPLACE => [
                'abc' => 'ABC Country',
                'def' => 'DEF Region',
            ],
        ],
    ]));

$form = $vb->form()
    ->add('name', $vb->text([Required::class]))
    ->add('address', $address);

有效的输入可能如下所示；

$input = [
    'name' => 'test-nested',
    'address' => [
        'zip' => '12345',
        'address' => 'city, street 101',
        'region' => 'abc',
    ]
];
$result = $form->verify($input);
echo $result->getChild('address')->getChild('region')->value(); // 'ABC Country'

一对多表单

使用 addRepeatedForm 方法在另一个表单中添加一对多表单。

$posts = $vb->form()
    ->add('title', $vb->text([
        Required::class,
    ]))
    ->add('publishedAt', $vb->date())
    ->add('size', $vb->integer([
        Required::class,
    ]));
$form = $vb->form()
    ->add('name', $vb->text([Required::class]))
    ->addRepeatedForm('posts', $posts);

有效的输入可能如下所示

$input = [
    'name' => 'test-one-to-many',
    'posts' => [
        ['title' => 'first title', 'size' => 1234],
        ['title' => 'more tests here', 'publishedAt' => '2019-04-01', 'size' => 2345],
    ],
];
$result = $form->verify($input);

验证数组

要验证数组输入，在构建链时指定 multiple，如下所示；

$tests = $vb->text([
    'multiple' => true, // specify multiple!
    StringLength::class => [StringLength::LENGTH => 3],
]);
$result = $tests->verify(['test', 'me']);

如上例中的 StringLength 筛选器之类的筛选器将应用于数组中的每个值。

要应用于整个数组的筛选器，指定筛选器如下所示；

$tests = $vb->text([
    'multiple' => [
        Required::class,
    ],
    StringLength::class => [StringLength::LENGTH => 5],
]);
$result = $tests->verify(['test', 'me']);

区域设置

在构建 ValidationBuilder 时指定区域设置（例如 'en'、'ja' 等）。

$vb = new ValidatorBuilder('ja');

或指定构建器可以找到消息和类型定义文件的文件夹

$vb = new ValidatorBuilder('/dir/to/my/locale');

文件夹必须包含： validation.message.php 和 validation.types.php 文件。

validation.message.php

一个返回错误消息数组的 php 文件。

return [
    'filter_error_type' => 'error message here',
    ...
];

validation.types.php

一个返回每个类型的筛选器的 php 文件。

return [
    'type-name' => [
        'filter-name', 
        'filter-with-option' => ['options' => 'here'],
    ], ...
];

预定义类型

t.b.w.

文本

  • 验证有效的 UTF-8 字符串，最大 1MB 的 string。
  • 预定义过滤器
    • ValidateUtf8String
    • 默认值：空字符串

email

  • 验证有效的 UTF-8 字符串，最大 1MB 的输入，以及有效的电子邮件 string。
  • 预定义过滤器
    • ValidateUtf8String
    • 默认值：空字符串
    • 匹配：EMAIL

integer

  • 验证有效的 UTF-8 数字字符串，并将其转换为 integer。
  • 预定义过滤器
    • ValidateInteger
    • 默认值：NULL

float

  • 验证有效的 UTF-8 数字字符串，并将其转换为 float。
  • 预定义过滤器
    • ValidateFloat
    • 默认值：NULL

date

  • 验证有效的 UTF-8 日期格式字符串，并将其转换为 \DateTimeImmutable 对象。
  • 预定义过滤器
    • ValidateDateTime
    • 默认值：NULL

datetime

  • 验证有效的 UTF-8 日期格式字符串，并将其转换为 \DateTimeImmutable 对象。
  • 预定义过滤器
    • ValidateDateTime
    • 默认值：NULL

month

  • 验证有效的 UTF-8 日期格式字符串，并将其转换为 \DateTimeImmutable 对象。
  • 预定义过滤器
    • ValidateDateTime
    • 默认值：NULL

digits

  • 验证只包含数字的有效 UTF-8 字符串，并将其转换为 string。
  • 预定义过滤器
    • ValidateDateTime
    • 默认值：空字符串

time

timeHi

dateYMD

预定义过滤器

FilterArrayToValue

  • 将数组输入转换为单个文本值。
  • 参数：['fields' => ['y', 'm'], 'format' => '%d.%d', 'implode' => '...']
    • fields：必需。指定数组键名列表。
    • format：可选。用于数组值的 sprintf 格式。
    • implode：可选。如果未定义 format，则使用字符（默认为 '-'）连接值。

示例代码

$filter = new FilterArrayToValue([
    'fields' => ['y', 'm', 'd'],
    'format' => '%d.%02d.%02d',
]);

ValidateMbString

  • 转换日文假名风格。
  • 参数: ['type' => 'convert']
    • type: 必需。用于 mb_convert_kana 的转换选项。默认是 MB_ZEN_KANA。
  • 可用的类型值
    • FilterMbString::MB_ZEN_KANA: 将半角假名转换为全角假名。
    • FilterMbString::MB_HANKAKU: 将全角字母和数字转换为半角。
    • FilterMbString::MB_MB_ZENKAKU: 将所有字符转换为全角。
    • FilterMbString::MB_HAN_KANA: 尽可能地将所有字符转换为半角。
    • FilterMbString::MB_HIRAGANA: 将所有假名转换为全角平假名。
    • FilterMbString::MB_KATAKANA: 将所有假名转换为全角片假名。
  • 尚未测试。
$filter = new FilterMbString(['type' => FilterMbString::MB_HANKAKU]);
$result = $filter(new Result('ｚｅｎｋａｋｕ＠ｅｘａｍｐｌｅ．ｃｏｍ'));
echo $result->value(); // zenkaku@example.com

ValidateValidUtf8

  • 检查输入值是否为有效的UTF-8字符。
  • 优先级: FilterInterface::PRIORITY_SECURITY_FILTERS
  • 错误: 如果出错，将输入值替换为空字符串 ('')。
    • FilterValidUtf8::INVALID_CHAR : 无效的UTF-8字符。
    • FilterValidUtf8::ARRAY_INPUT : 输入是一个数组。

ValidateDateTime

  • 将字符串输入转换为 \DateTimeImmutable 对象。
  • 参数: ['format' => 'YY.m.d'].
    • 格式: 可选。如果设置，则使用 \DateTimeImmutable::createFromFormat
$filter = new ConvertDateTime(['format' => 'm/d/Y']);
$result = $filter(new Result('04/01/2019'));
$date = $result->value(); // should be DateTimeImmutable object.

ValidateInteger

  • 检查输入值是否为数字，并将值转换为整数。
  • 错误: 如果值不是数字，或者值是一个数组。
  • 参数: 无。

ValidateFloat

  • 检查输入值是否为数字，并将值转换为浮点数。
  • 错误: 如果值不是数字，或者值是一个数组。
  • 参数: 无。

ValidateLetterType

  • 对由某些类型的字母组成的输入值进行清理。
    • 参数: [ValidateLetterType::TYPE => ValidateLetterType::DIGITS_ONLY]
      • ValidateLetterType::TYPE: 必需。指定以下类型之一。
        • ValidateLetterType::DIGITS_ONLY: 仅数字（0-9）。
        • ValidateLetterType::AL_NUM_ONLY: 仅字母数字字符（0-9a-zA-Z）。
        • ValidateLetterType::CODE_ONLY: 仅一些代码（-_0-9a-zA-Z）。

DefaultValue

  • 如果输入为null或空，则设置值到默认的 $default。
  • 参数: ['default' => 'some value']
    • 默认值: 可选。如果没有设置，则使用空字符串 ('')。

Required

  • 验证输入值不为null或空字符串。
  • 如果失败，则终止进一步验证。
  • 参数: [Required::NULLABLE => true].
    • Required::NULLABLE: 已弃用。请使用 Nullable 代替。默认为false。如果值为空（即null、空字符串或空数组），则中断验证链。

RequiredIf

  • 如果设置了 field 名称，或者 field 的值是 value，则验证输入值不为null或空字符串。
  • 如果失败，则终止进一步验证。
  • 参数: [RequiredIf::FIELD => 'other', RequiredIf::VALUE => 'val']
    • RequiredIf::FIELD: 字符串。必需。设置其他字段名称以引用。
    • RequiredIf::VALUE: 字符串、整数、浮点数或数组。可选。如果其他字段具有指定的值，则设置值（或数组中的值）。
    • Required::NULLABLE: 已弃用。请使用 Nullable 代替。默认为false。如果值为空（即null、空字符串或空数组），则中断验证链。
$required = new RequiredIf([
    RequiredIf::FIELD => 'type', 
    RequiredIf::VALUE => 'check-me',
    RequiredIf::NULLABLE => true,
]);

Nullable

  • 如果输入值为空，则中断验证链/循环。停止进一步验证，如果输入为空值，则可能会失败。因此，此过滤器允许NULLABLE值，而不管后续的过滤器如何。
  • 用于非必需字段，但具有某些过滤器（正则表达式），如果输入为空，可能会失败。
  • 参数: 无。

StringLength

  • 检查输入值的字符长度。设置任何参数，length、max 或 min，但可能没有必要设置所有选项。
  • 参数: ['length' => 5, 'max' => 6, 'min' => 7, 'message' => 'error message']
    • length: 可选。指定输入字符串的确切长度。
    • max: 可选。设置输入字符串的最大长度。
    • min: 可选。设置输入字符串的最小长度。
    • message: 可选。设置错误消息。

ConfirmWith

  • 通过比较另一个输入值来确认输入值。
  • 参数: ['with' => 'field_name_to_confirm_with']
    • 可选。如果未设置，则使用 {name}_confirmation
  • 尚未测试。

InArray

  • 检查输入值是否在给定的数组中定义。
  • 参数：['choices' => ['A', 'B',...] 或 ['replace' => ['a' => 'A', 'b' => 'B']]。必须指定 choices 或 replace 选项。
    • choices：可选数组。指定可用选项作为数组。
    • replace：可选的哈希数组。替换值。
    • strict：可选。检查值时的严格选项。默认为 true。
$filter = new InArray([
    'choices' => [
        $obj1->getKey(), $obj1,
        $obj2->getKey(), $obj2,
    ],
    'replace' => true,
    'strict' => true,
]);

RegEx

  • 检查正则表达式。
  • 参数：[RegEx::PATTERN => '[A-D][0-9]{1}', RegEx::MESSAGE => '错误信息']
    • RegEx::PATTERN：必需。设置正则表达式模式。模式被评估为 /\A{$pattern}\z/us。
    • RegEx::MESSAGE：可选。设置错误信息。
  • 尚未测试。

ValidateMatch

  • 使用 filter_var 验证输入字符串是否为有效的 UTF-8 和预定义类型。
  • 默认情况下，错误信息根据类型选择。
  • 参数：[Match::TYPE=> 'filter_var_filter']
    • Match::TYPE：必需。以下可用类型中的字符串
      • Match::IP：验证 IP 地址。
      • Match::EMAIL：验证电子邮件地址。
      • Match::URL：验证 URL。
      • Match::MAC：验证 MAC 地址。
  • 尚未测试。

StringCases

StringTrim