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开发。

维护者


Colin Tucker	Praxis Interactive

hestec / silverstripe-validator

维护者

详细信息