Validation - 类別

配置

Validation 类别可以选择性的透过全域应用程序配置档案 app/config/config.php 来配置。定义一个名为 'validation' 的段落，在其中以下设定可以被定义：

''

'<ul>'

'</ul>'

'<li>'

'</li>'

false

true

如果全域配置中缺少这些值中的一个或多个时，类别将使用定义在这张表中的预设值。

用法

要开始验证你需要建立一个物件，这可以是名为 "default" 的预设物件， 或者你可以命名它如果你需要多个验证物件。

// 使用预设
$val = Validation::forge();

// ……或给它命名
$val = Validation::forge('my_validation');

在让它实例化之后，你可以开始添加栏位给它。这与使用 Fieldset 类别的运作完全一样， 然而这里我们只记录首选的用法。

$val = Validation::forge('my_validation');

// 添加一个 username 栏位，给它 "Your username" 标籤并让它为必要
$val->add('username', 'Your username')->add_rule('required');

// 现在添加另一个 password 栏位，并让它必须包含至少 3 个最多 10 个字元
$val->add('password', 'Your password')->add_rule('required')
    ->add_rule('min_length', 3)
    ->add_rule('max_length', 10);

// 现在为 gender 添加另一个栏位，并要求它包含 "M" 或 "F" 其中之一。
$val->add('gender', 'Your gender')->add_rule('required')
    ->add_rule('match_collection', array('M', 'F'));

add_rule() 方法的第一参数除了提供的验证方法之外，可以包含 PHP 原生函式名称、任何有效的 PHP 回呼（callback）和闭包（Closure）。该方法会取得要被验证做为其第一参数的值， 以及任何更多可以给 add_rule() 方法的参数值。

我们也提供了更短的语法，相对这非常受限。它不会接受阵列回呼（array-callback）、 闭包（closure）或字串以外的参数。你也不能在你的形式中使用管道符号（|）当你使用 'match_pattern'规则， 因为该符号被用来拆分定义的规则。

// 与上面範例相同的栏位
$val = Validation::forge('my_validation');
$val->add_field('username', 'Your username', 'required');
$val->add_field('password', 'Your password', 'required|min_length[3]|max_length[10]');
$val->add_field('gender', 'Your gender', 'required|match_collection[M,F]');

一旦所有栏位都被添加，你可以执行你的验证。这将预设为 $_POST 输入， 但可以在给一个输入阵列时被扩充并覆写。

// 执行刚发布的验证
if ($val->run())
{
	// 在验证成功时处理你的东西
}
else
{
	// 验证失败
}

// 替代上面，覆写 POST 中的 username，password 仍在 POST 中被徵询
if ($val->run(array('username' => 'something')))

在验证执行后，有三个关于输入资讯的可用方法：

// 取得一个验证成功栏位 => 值配对的阵列
$vars = $val->validated();
// 取得一个验证错误为栏位 => 错误配对的阵列
$errors = $val->error();
// 取得一个已验证输入的阵列，这合併了 post 和给 run() 的输入
$input = $val->input();

// 这些方法也都可以只取得单一栏位的值
$var = $val->validated('username');

验证也可以部份执行，在这种情况下甚至 required 栏位会被忽略，当他们不在 POST 中或输入给 run()。 透过设定执行的第二参数为 true 能做到。

// 这会只验证 password，当 username 没有出现在 POST 时
$val->run(array('password' => 'whatever'), true);

验证规则

请注意，所有方法（甚至 min_length）在空白输入时也会回传 true。 也要要求栏位你应该添加 "required" 规则。

这些规则都可以像以下这样被使用：

// 一般使用範例，一个没参数的规则，和另一个有参数的规则
$val->add('email', 'Email address')->add_rule('match_value', 'me@mydomain.com', true)->add_rule('valid_email');
$val->add_field('email', 'Email address', 'match_value[me@mydomain.com,1]|valid_email');

规则表

有效字串规则

验证字串是否坚持 $flags 参数设定的条件。 接受的标誌有：

扩充 Validation 类别

扩充 Validation 类别有几种办法：

1. 扩充核心类别像扩充核心类别中的叙述

2. 在 app/classes/myrules.php 中建立一个类别（例如）

// app/classes/myrules.php
class MyRules
{
	// 注意这是一个静态方法
	public static function _validation_unique($val, $options)
	{
		list($table, $field) = explode('.', $options);

		$result = DB::select(DB::expr("LOWER (\"$field\")"))
		->where($field, '=', Str::lower($val))
		->from($table)->execute();

		return ! ($result->count() > 0);
	}

	// 注意这是一个非静态方法
	public function _validation_is_upper($val)
	{
		return $val === strtoupper($val);
	}

}

// 并且像这样呼叫它：
$val = Validation::forge();

// 注意静态与非静态验证规则之间的差异：

// 静态地添加，将只能使用静态方法
$val->add_callable('MyRules');

// 非静态地添加，将可以使用静态与非静态方法
$val->add_callable(new MyRules());

$val->add('username', 'Your username', array(), array('trim', 'strip_tags', 'required', 'is_upper'))
	->add_rule('unique', 'users.username');

3. 从模型呼叫回呼（callback），它运作就像上面所描述的方法，但我们只需要用其他方式呼叫它：

$val = Validation::forge();
$val->add_model('Model_User');

注意： 你需要用于方法的 '_validation_' 前缀以在验证中是可用的。

注意： 如果你传递类别名称做为一个字串，验证方法必须被定义为静态。如果方法不是静态，你将必须传递一个物件实例做为 callable()。

使用 Validation::active() 和 Validation::active_field() 来分别取得目前活跃的 validation 实例与目前被验证的栏位会是有用的。

例如，在上述你可以这样做：

public static function _validation_unique($val, $options)
{
	Validation::active()->set_message('unique', 'The field :label must be unique, but :value has already been used');
...
}