README

一个验证组件，专为多字节（例如日语）支持而设计。功能包括，如

• 与代码补全良好配合。
• 将多个值合并为单个值（例如：bd_y, bd_m, bd_d 到 bd）。
• 预设规则的顺序。对于处理日语字符至关重要。
• 易于编写逻辑。

许可证

MIT 许可证

PSR

PSR-1, PSR-2, 和 PSR-4。

安装

composer require "wscore/validation": "^2.0"

基本用法

工厂对象

使用 ValidationFactory 开始验证数组。例如，

use \WScore\Validation\ValidationFactory;

$factory = new ValidationFactory();    // use English rules and messages.
$factory = new ValidationFactory('ja'); // use Japanese rules and messages.

$input = $factory->on($_POST); // create a validator object. 

验证

验证数组的示例代码

// set rules for input data. 
$input->set('name')->asText()->required());  // a text
$input->set('type')->asText()->in('old', 'young', 'teenager'); // a selected text
$input->set('age')->asInteger()->range([10, 70]);  // an integer between 10-70

// maybe update rules based on age?
$age = $input->get('age'); 
if ($age > 12) {
    $input->getRules('type')->required();
} else {
    $input->setValue('type', 'teenager');
}
// result of validation. 
if ($input->fails()) {
    $messages   = $input->messages(); // get error messages
    $badInputs  = $input->getAll(); // get all the value including invalidated one. 
    $safeInputs = $input->getSafe(); // get only the validated value. 
} else {
    $validatedInputs  = $input->getAll(); // validation success! 
}

• set($key) 为 $key 设置验证规则。
• get($key) 返回验证后的值，如果验证失败则返回 false。
• getRules($key) 返回现有规则对象以进行修改。
• fails() 或 passes() 方法将评估所有规则，并返回布尔值，表示是否所有验证规则都已通过。
• getAll() 返回所有值，包括无效的值，而 getSafe() 仅返回 验证后的值。
• getMessages() 返回所有无效的错误消息。

类型

类型 规则是针对给定验证类型的标准规则。在 set 方法之后，使用 as{Type}() 选择验证类型。

$input->set('key')->as{Type}()->{validationRule}();

以下预定义的类型与 HTML5 输入类型兼容。

• binary
• text
• mail
• number
• integer
• float
• date
• datetime
• month
• tel

还有一些多字段类型。

• dateYMD
• dateYM
• dateHis
• timeHis
• timeHi

这些在 Locale/{locale}/validation.types.php 文件中定义。

验证规则

有许多验证规则。您可以像之前的示例代码中那样将它们链接起来；

$input->set('mail')->asMail()->required()->string(Rules::STRING_LOWER)->confirm('mail2'));

可用的过滤器，即可能更改值的过滤器

• message(string $message)：设置错误消息。
• multiple(array $parameter)：设置多个字段输入，例如 Y、m 和 d。
• array()：允许数组输入。
• noNull(bool $not = true)：删除 null 字符。
• encoding(string $encoding)：根据字符编码进行验证（默认为 UTF-8）。
• mbConvert(string $type)：转换假名（日语）。
  • mbToHankaku()：将半角字符转换为全角。
  • mbToZenkaku()：将全角字符转换为半角。
  • mbToHankakuKatakana()：将全角片假名转换为半角。
  • mbToHiragana()：将片假名转换为全角平假名。
  • mbToKatakana()：将平假名转换为全角片假名。
• trim(bool $trim = true)：修剪输入字符串。
• sanitize(string $type)：净化值。
  • sanitizeMail()：用于邮件输入的净化。
  • sanitizeFloat()：用于浮点数的净化。
  • sanitizeInt()：用于整数的净化。
  • sanitizeUrl()：用于 URL 输入的净化。
  • sanitizeString()：作为字符串进行净化。
• string(string $type)：将字符串转换为大写/小写等。
  • strToLower()：将字符串转换为小写字母。
  • strToUpper()：将字符串转换为大写字母。
  • strToCapital()：将字符串转换为首字母大写。
• default(string $value)：如果未设置，则设置默认值。

所有验证器，即检查值是否满足要求

• required(bool $required = true)：必填值
• requiredIf(string $key, array $in=[])：如果$key存在（或在$in中），则设置必填。
• loopBreak(bool $break = true)：中断过滤器循环。
• code(string $type):
• maxLength(int $length)：最大字符长度。
• pattern(string $reg_expression)：preg_match模式。
• matches(string $match_type)：预设正则表达式模式（数字、整数、浮点数、代码、邮件）。使用matches规则比patterns规则提供更具体的错误消息。
  • matchNumber()：匹配数值输入。
  • matchInteger()：匹配整数输入。
  • matchFloat()：匹配浮点数输入。
  • matchCode()：匹配"[-_0-9a-zA-Z]"。
  • matchMail()：匹配简单的邮件模式。
• kanaType(string $match_type)：检查假名类型。
  • mbOnlyKatakana()：验证仅全角片假名。
  • mbOnlyHiragana()：验证仅全角平假名。
  • mbOnlyHankaku()：验证仅半角字符（即ASCII）。
  • mbOnlyHankakuKatakana()：验证仅半角片假名。
• min(int $min)：最小数值。
• max(int $max)：最大数值。
• range(array $range)：范围[min, max]。
• datetime(string|bool $format = true)：检查带有格式的日期时间。
• in(array $choices)：检查可能的值列表。
• inKey(array $choices)：检查值是否作为键定义（比in更快）。
• confirm(string $key)：与另一个$key进行确认。

高级功能

验证输入列表

要验证输入数据列表，例如复选框，请使用以下格式的array()规则。当验证失败时，它将错误消息作为数组返回。

$input->source(array('list' => [ '1', '2', 'bad', '4' ]));
$input->set('list')->asInteger()->array()->required();
if ($input->fails()) {
    $values = $validation->get('list');
    $goods  = $validation->getSafe();
    $errors = $validation->message();
}
/*
 * $values = [ '1', '2', '', '4' ];
 * $goods  = array('list' => [ '1', '2', '4' ]);
 * $errors = array('list' => [ 2 => 'required item' ]);
 */

多个输入

WScore/Validation可以处理日期等单独输入字段作为一个输入。例如，date、dateYM、datetime类型。

$input->source([ 'bd_y' => '2001', 'bd_m' => '09', 'bd_d' => '25' ]);
echo $validation->set('bd')->asDateYMD(); // 2001-09-25

使用multiple规则构建自己的多个输入，如下所示，

// for inputs like,
// [ 'ranges_y1' => '2001', 'ranges_m1' => '09', 'ranges_y2' => '2011', 'ranges_m2' => '11' ]
$input->set('ranges')
    ->asText()
    ->multiple([
        'suffix' => 'y1,m1,y2,m2',
        'format' => '%04d/%02d - %04d/%02d'
    ])
    ->pattern('[0-9]{4}/[0-9]{2} - [0-9]{4}/[0-9]{2}')
    ->message('set year-month range');

其中suffix列出了输入的后缀，format是使用sprintf的格式字符串。

确认以比较值

对于密码或电子邮件验证，使用两个字段的输入来比较它们。

$input->source([ 'text1' => '123ABC', 'text2' => '123abc' ] );
echo $validation->set('text1')
    ->asText()
    ->string('lower')
    ->confirm('text2'); // 123abc

请注意，实际输入字符串是不同的。在将字符串转换为小写后，它们变为相同。

过滤器顺序

某些过滤器必须按特定顺序应用...

echo $input->set('ABC')->asText()->pattern('[a-c]*')->string('lower'); // 'abc'
# must lower the string first, then check for pattern...

自定义验证

使用闭包作为自定义验证过滤器。

/**
 * @param ValueTO $v
 */
$filter = function( $v ) {
    $val = $v->getValue();  // get the value to validate. 
    $val .= ':customized!'; // you can alter the value.
    $v->setValue( $val );   // and reset the value. 
    
    $v->setError(__METHOD__); // set error if the custome validation fails.
    $v->setMessage('Closure with Error'); // you can set error message as well.
};
$input->asText('test')->addCustom('myFilter', $filter);

您不能传递参数（闭包是参数）。参数是ValueTO对象，可以用于处理错误和消息。

将错误设置到ValueTO将中断过滤器循环，即不再评估其他规则。

设置值和错误

要设置值或错误到验证器，请使用setValue和setError方法。

$input->setValue('extra', 'good'); // set some value.
$input->setError('bad', 'why it is bad...');  // set error. 
if ($input->fails()) {
    echo $input->getAll()['extra'];  // 'good' 
    echo $input->getMessages('bad'); // 'why it is bad...'
}

设置错误将使fails()方法返回true。

修改错误消息

要使用自己的消息，创建一个目录，例如your/path/<locale>，然后创建或复制以下文件。

• validation.filters.php
• validation.messages.php
• validation.types.php

$factory = new ValidationFactory('locale', 'your/path');
$input = $factory->on($_POST);

文件validation.messages.php包含默认错误消息作为数组，其外观如下

return array(
    // 5. general error message 
    0           => 'invalid input',
    // 4. messages for types
    '_type_'    => [
        'mail'     => 'invalid mail format',
        ...
    ],
    // 3. specific messages for method
    'encoding'  => 'invalid encoding',
    ...
    // 2. message for matches and parameter
    'matches'   => [
        'number' => 'only numbers (0-9)',
        ...
    ],
);

而错误消息的确定如下

1. 由message规则设置的message
2. 方法和参数特定的消息
3. 方法和参数特定的消息
4. 方法和参数特定的消息，然后
5. 类型特定的消息

1. 使用message规则

使用message方法设置其消息。

$input->set('text')->asText()->required()->message('Oops!'));
echo $input->getMessage('text'); // 'Oops!'

2. 方法和参数特定的消息

一些过滤器，如matches和kanaType，具有基于参数的消息。

$input->set('int')->asText()->matchInteger();
$input->set('kana')->asText()->mbOnlyKatakana();
echo $input->getMessage('int'); // 'not an integer'
echo $input->getMessage('kana'); // 'only in katakana'

3. 方法特定的消息

一些过滤器，如required，具有特定的过滤器消息。

$input->set('text')->asText()->required();
echo $input->getMessage('text'); // 'required item'

4. 类型特定的消息

大多数规则类型都有自己的消息。

$input->set('date')->asDate();
echo $input->getMessage('date'); // 'invalid date'

5. 一般消息

如果所有上述规则都失败，则使用通用消息。

$input->set('text')->asText()->pattern('[abc]');
echo $input->getMessage('text'); // 'invalid input'