README

为 SilverStripe v4 提供的表单验证模块，支持替代客户端后端和可定制的验证规则。默认使用 Parsley.js 作为验证后端。默认配置适用于 Bootstrap v4 表单。

内容

需求
安装
配置
使用
规则
问题
待办事项
贡献
归属
维护者
许可

需求

SilverStripe 框架 v4
Bootstrap v4 (用于默认配置)

安装

通过 Composer 安装

$ composer require silverware/validator

配置

与所有 SilverStripe 模块一样，配置通过 YAML 完成。使用 SilverStripe 依赖注入器配置验证器后端。该模块包含使用 Parsley.js 的后端。

SilverStripe\Core\Injector\Injector:
  ValidatorBackend:
    class: SilverWare\Validator\Backends\ParsleyBackend

该模块被设计为尽可能的“后端无关”。虽然 Parsley.js 非常强大，应该能满足大多数验证需求，但你当然可以自己实现后端并使用配置将其集成到验证器前端。

使用

要使用您的应用中的验证器，只需在代码的头部 use 验证器类

use SilverWare\Validator\Validator;

您还需要 use 您想要应用于表单的验证器规则类，例如

use SilverWare\Validator\Rules\LengthRule;
use SilverWare\Validator\Rules\PatternRule;
use SilverWare\Validator\Rules\RequiredRule;

在返回 Form 的控制器方法中创建验证器实例，例如

public function Form()
{
    $fields  = FieldList::create([
        ...
    ]);
    
    $actions = FieldList::create([
        ...
    ]);
    
    $validator = Validator::create();
    
    // define validator rules here!
    
    $form = Form::create($this, 'Form', $fields, $actions, $validator);
    
    return $form;
}

现在您可以使用下面的方法定义您的验证器规则。

验证器规则

SilverWare 验证器附带了许多预构建的规则，您可以立即使用它们来验证您的表单。这些规则支持客户端和服务器端验证。SilverWare 验证器包括以下规则类

AlphaNumRule
CheckRule
ComparisonRule
DateRule
DigitsRule
DomainRule
EmailRule
EqualToRule
IntegerRule
LengthRule
MaxCheckRule
MaxLengthRule
MaxRule
MaxWordsRule
MinCheckRule
MinLengthRule
MinRule
MinWordsRule
NotEqualToRule
NumberRule
PatternRule
RangeRule
RemoteRule
RequiredRule
URLRule
WordsRule

以下将详细介绍每个规则。

设置规则

要为特定表单字段设置规则，请使用 setRule 方法，并传递字段名和规则实例。例如

$validator->setRule(
    'MyFieldName',
    LengthRule::create(10, 20) // this field's value must be 10-20 characters in length
);

要为字段设置多个规则，可以使用 setRules 方法并传递一个规则实例数组

$validator->setRules(
    'MyDomainName',
    [
        RequiredRule::create(),  // this field is required
        DomainRule::create()     // this field must be a valid domain name
    ]
);

必填字段

由于字段通常对于几乎任何表单都是必需的，因此提供了一些快捷方法来定义必填字段。使用 addRequiredField 与字段名和可选的自定义消息参数

$validator->addRequiredField('MyRequiredField');
$validator->addRequiredField('MyOtherRequiredField', 'Dis field be mandatory, yo!');

要批量添加必填字段，请使用 addRequiredFields 与字段名数组

$validator->addRequiredFields([
    'ThisFieldIsRequired',
    'SoIsThisField',
    'AndThisField'
]);

自定义消息

所有规则类都包含一个默认消息，当规则验证失败时显示给用户。您可以通过在规则上使用 setMessage 方法来自定义消息，例如

$validator->setRule(
    'MyAge',
    MaxRule::create(130)->setMessage(
        'I find it hard to believe you are over 130 years old!'
    )
)

禁用验证

默认情况下，SilverWare Validator 执行客户端和服务器端验证。虽然建议启用两种验证方法，但如果您需要禁用其中一种，可以使用以下方法

$validator->setClientSide(false);  // disables client-side validation
$validator->setServerSide(false);  // disables server-side validation

触发事件

默认情况下，开箱即用的验证器 Parsley.js 会触发字段更改时的表单验证。您可以通过在后端使用 setTriggerOn 方法来自定义何时触发验证，例如

$validator->getBackend()->setTriggerOn([
    'focusin',
    'focusout'
]);

您也可以简单地传递触发事件作为字符串

$validator->getBackend()->setTriggerOn('focusin focusout');

Parsley.js 支持通过任何标准 jQuery 事件触发。

规则

AlphaNumRule

use SilverWare\Validator\Rules\AlphaNumRule;

测试输入的值是否是字母数字字符串，仅包含基本字母、数字和下划线字符。

$validator->setRule(
    'MyFieldName',
    AlphaNumRule::create()
);

CheckRule

use SilverWare\Validator\Rules\CheckRule;

用于类似 OptionsetField（如 CheckboxSetField）的控件。确保用户在给定的 $min 和 $max 参数之间选择一定数量的选项。

$validator->setRule(
    'MyCheckboxSet',
    CheckRule::create(2, 4)  // user must select between 2 and 4 options
);

ComparisonRule

use SilverWare\Validator\Rules\ComparisonRule;

使用指定的比较类型比较一个字段的值与另一个字段的值

ComparisonRule::LESS_THAN
ComparisonRule::LESS_THAN_OR_EQUAL
ComparisonRule::GREATER_THAN
ComparisonRule::GREATER_THAN_OR_EQUAL

$validator->setRule(
    'MyLesserValue',
    ComparisonRule::create(
        ComparisonRule::GREATER_THAN,
        'MyGreaterValue'
    )
);

DateRule

use SilverWare\Validator\Rules\DateRule;

确保输入的值是特定格式的日期。规则构造函数支持两个参数。第一个参数是使用客户端 Moment.js 规范的必需日期格式。

可选的第二个参数指定服务器端 PHP 日期格式，但如果省略第二个参数，规则将适当地转换客户端格式。

$validator->setRule(
    'MyDateField',
    DateRule::create('YYYY-MM-DD')  // ensures an ISO standard date, e.g. 2017-05-12
);

DigitsRule

use SilverWare\Validator\Rules\DigitsRule;

确保仅输入数字，即仅数字 0-9。

$validator->setRule(
    'MyDigitsField',
    DigitsRule::create()
);

DomainRule

use SilverWare\Validator\Rules\DomainRule;

测试输入的值是否是有效的域名。支持新的顶级域名（TLD）和 localhost。

$validator->setRule(
    'MyDomainName',
    DomainRule::create()
);

EmailRule

use SilverWare\Validator\Rules\EmailRule;

确保值是有效的电子邮件地址。

$validator->setRule(
    'MyEmailField',
    EmailRule::create()
);

EqualToRule

use SilverWare\Validator\Rules\EqualToRule;

确保一个字段的值与另一个字段的值相等。

$validator->setRule(
    'MyFirstValue',
    EqualToRule::create('MySecondValue')
);

IntegerRule

use SilverWare\Validator\Rules\IntegerRule;

测试输入的值是否是有效的正整数或负整数。

$validator->setRule(
    'MyIntField',
    IntegerRule::create()
);

LengthRule

use SilverWare\Validator\Rules\LengthRule;

确保输入值的长度在指定的 $min 和 $max 范围内。

$validator->setRule(
    'MyFieldName',
    LengthRule::create(20, 40)  // value must be between 20-40 characters in length
);

MaxCheckRule

use SilverWare\Validator\Rules\MaxCheckRule;

用于类似 OptionsetField（如 CheckboxSetField）的控件。指定用户只能选择最大数量的选项。

$validator->setRule(
    'MyCheckboxSet',
    MaxCheckRule::create(4)  // user can select a maximum of 4 options
);

MaxLengthRule

use SilverWare\Validator\Rules\MaxLengthRule;

确保输入值的最大长度。

$validator->setRule(
    'MyFieldName',
    MaxLengthRule::create(40)  // value must be 40 characters in length or less
);

MaxRule

use SilverWare\Validator\Rules\MaxRule;

测试数值是否小于或等于指定的金额。

$validator->setRule(
    'MyNumberField',
    MaxRule::create(255)  // number value must be 255 or less
);

MaxWordsRule

use SilverWare\Validator\Rules\MaxWordsRule;

确保值不超过指定的单词数量。

$validator->setRule(
    'MyTextArea',
    MaxWordsRule::create(50) // value must be 50 words or less
);

MinCheckRule

use SilverWare\Validator\Rules\MinCheckRule;

用于类似 OptionsetField（如 CheckboxSetField）的控件。确保用户选择最小数量的选项。

$validator->setRule(
    'MyCheckboxSet',
    MinCheckRule::create(2)  // user must select at least 2 options
);

MinLengthRule

use SilverWare\Validator\Rules\MinLengthRule;

确保输入值的最小长度。

$validator->setRule(
    'MyFieldName',
    MinLengthRule::create(20)  // value must be at least 20 characters in length
);

MinRule

use SilverWare\Validator\Rules\MinRule;

测试数值是否大于或等于指定的金额。

$validator->setRule(
    'MyNumberField',
    MinRule::create(42)  // the entered value must be 42 or greater
);

MinWordsRule

use SilverWare\Validator\Rules\MinWordsRule;

确保值至少包含指定的单词数量。

$validator->setRule(
    'MyTextArea',
    MinWordsRule::create(20)  // value must contain at least 20 words
);

NotEqualToRule

use SilverWare\Validator\Rules\NotEqualToRule;

确保一个字段的值与另一个字段的值不相等。

$validator->setRule(
    'MyFirstValue',
    NotEqualToRule::create('MySecondValue')
);

NumberRule

use SilverWare\Validator\Rules\NumberRule;

测试输入的值是否是数值，即整数或浮点数。

$validator->setRule(
    'MyNumericValue',
    NumberRule::create()  // value must be numeric
);

PatternRule

use SilverWare\Validator\Rules\PatternRule;

使用正则表达式测试输入值。请确保您的正则表达式在 JavaScript 和 PHP preg_match 中都能正常工作，以便客户端和服务器端验证函数能正确执行。

$validator->setRule(
    'MyFieldName',
    PatternRule::create('/ware$/')  // ensures the entered string ends with 'ware'
);

RangeRule

use SilverWare\Validator\Rules\RangeRule;

指定输入值必须介于其间的数字范围。

$validator->setRule(
    'MyNumericValue',
    RangeRule::create(1, 5)  // value must be between 1 and 5
);

RemoteRule

use SilverWare\Validator\Rules\RemoteRule;

使用 Ajax 请求在客户端测试值，并使用 Guzzle 在提交到服务器时测试值。

规则构造函数允许以下参数

$rule = RemoteRule::create(
    $url,  // url to call
    $params,  // request parameters, e.g. ['myVar' => 123]
    $options, // options for request, e.g. ['type' => 'POST']
    $remoteValidator  // remote validator to use, 'default' or 'reverse'
);

例如，您可能使用 RemoteRule 来检查用户名是否可用

$validator->setRule(
    'MyUserName',
    RemoteRule::create(
        $this->Link('checkusername')  // controller method
    )->setMessage('That username is unavailable')
);

服务器将接收字段的名称及其值作为参数，例如 ?MyUserName=sallybloggs。默认情况下，如果 RemoteRule 收到 200-299 之间的 HTTP 状态码，则认为它是有效的。其他任何情况都将返回无效结果。

如果您想反转此行为，即 200-299 被视为无效，您可以使用“反向”模式

$validator->setRule(
    'MyUserName',
    RemoteRule::create(
        $this->Link('checkusername')
    )->setRemoteValidator('reverse')
);

有关使用远程验证的更多信息，请参阅 Parsley.js 文档。

RequiredRule

use SilverWare\Validator\Rules\RequiredRule;

将指定的字段定义为必填（强制）字段，用户必须完成。

$validator->setRule(
    'MyRequiredField',
    RequiredRule::create()
);

URLRule

use SilverWare\Validator\Rules\URLRule;

确保输入的值是有效的 URL。

$validator->setRule(
    'MyURL',
    URLRule::create()
);

WordsRule

use SilverWare\Validator\Rules\WordsRule;

确保输入的值介于 $min 和 $max 个单词之间。

$validator->setRule(
    'MyTextArea',
    WordsRule::create(10, 25)  // user must enter between 10 and 25 words
);

问题

请使用 GitHub 问题跟踪器提交错误报告和功能请求。

待办事项

测试

贡献

我们非常欢迎您的贡献，以帮助使此项目变得更好。请参阅贡献指南获取更多信息。

归属

使用由 Parsley.js，由 Guillaume Potier 提供。
使用由 Moment.js，由 Iskren Ivov Chernev 和其他人员提供。
使用由 Guzzle，由 Michael Dowling 和其他人员提供。
使用由 Bootstrap，由 Bootstrap 作者和 Twitter, Inc 提供。
灵感来源于 SilverStripe ZenValidator，由 Shea Dawson 提供。

silverware / validator

维护者

详细信息