校验库（Validation Library）

Kohana 的校验类（Validation Library）使用及其简单，通过表单可以校验任何的数据字段的数组，包括 $_POST 的数据信息。整个类包括校验的内置的规则，使其让你轻易地使用自定义的回调函数和 Kohana 校验辅助函数的预制函数，而且还可以自定义每个字段的错误信息。

扩展信息：官方文章 官方教程

通用数组一般设置为 __POST。数据数组可以合并为一个实体。

// 使用 $_POST 变量创建校验对象
$post = new Validation($_POST);
 
// 结合不同的数组
$post = new Validation(array_merge($_POST, $_FILES));
 
// 使用 factory 的方法链
$post = Validation::factory($_POST)->add_rules('field_name', 'required');
 
// 也可以使用 $_POST 数组自身 （不推荐）
$_POST = new Validation($_POST);

当您实例验证对象需要添加规则领域。共同的规则，如需要的是确定的图书馆。该图书馆的目的是无缝工作的有效帮手。

After you instantiate the Validation object you need to add rules to fields. Common rules such as required are defined by the library. The library is designed to work seamlessly with the valid helper.

实例：所有这些都是等价（相同）的

$post->add_rules('email', 'required', array('valid','email'));
$post->add_rules('email', 'required', 'valid::email'); 
$post->add_rules('email', 'required', 'email');

对于上面的实例，所有的规则都回到给函数，然后 'required' 检测字段是否是必要的。最后校验是否为正确的 email 格式。

当然你也可以使用通配符或 TRUE （规则会应用到所有字段）

$post->add_rules('*', 'required');

过滤器能够处理的数据字段之前和之后的实际验证。默认情况下，过滤器适用于所有的数据数组字段，但你也可以选择指定任何数量的数组字段进行过滤。任何 PHP 函数会接受并返回一个字符串可以被用来作为一个过滤器。函数需要额外的参数不能被用作过滤器。

// 使用 PHP 的 trim() 方法去除所有数组字段前后的空格
$post->pre_filter('trim');
 
// 使用 PHP 的 trim() 方法去除 "title" 字段前后的空格
$post->pre_filter('trim', 'title');
 
// 使用 PHP 的 trim() 方法去除 "title" 和 "email" 字段前后的空格
$post->pre_filter('trim', 'title', 'email');
 
// 仅对 "title" 字段执行一个回调
$post->pre_filter(array($this, 'a_custom_filter'), 'title');
 
// 使用 PHP 的 ucfirst() 方法使得 "title" 首字母大写
$post->post_filter('ucfirst', 'title');

除了添加规则之外，还可以添加自己的回调函数（callbacks）。回调是一个简单的方法，你可以自定义一些算法检查某个字段。这个方法通过一个参数传递校验对象（Validation object）到回调， 如果检测不通过，回调可以使用 add_error() 方法添加错误。

// 在这里例子里面，我们创建了一个自定义的回调函数，它的功能是校验数据库中 email 地址。
 
// // 添加回调，我们假设 $post 是一个验证对象，并在同一个控制器定义了回调，因此，我们使用, $this
$post->add_callbacks('email', array($this, '_unique_email'));
 
// 定义回调方法
 * 检查 email 的回调方法
 *
 * @param  Validation  $array   校验对象（Validation object）
 * @param  string      $field   检验的域名（name of field being validated）
 */
public function _unique_email(Validation $array, $field)
{
   // 检查存在于数据库
   $email_exists = (bool) ORM::factory('user')->where('email', $array[$field])->count_all();
 
   if ($email_exists)
   {
       // 添加错误到校验对象
       $array->add_error($field, 'email_exists');
   }
}

验证是通过 validate() 方法完成。它首先处理预过滤器，然后判定，回调和最后一个 post_filters。

如果在输入框遇到任何错误时，它增加字段当作数组的键值到验证错误数组。

如果发现任何的错误，返回 FALSE 布尔型，如果灭有发现错误，返回 TRUE。

if($post->validate())
{
   echo '没有发现验证错误';
}
else
{
   echo '发现验证错误';
   $errors = $post->errors();
   foreach ($errors as $key => $val)
   {
       echo $key.' failed rule '.$val.'<br />';
   }
}

通过使用 add_error() 方法添加错误处理到验证错误数组。

$post->add_error( 'password', 'pwd_check');

Kohana 默认没有为验证定义错误信息。错误信息需自定义文件并存放在 application/i18n 目录。

实例：application/i18n/en_US/form_errors.php 定义默认错误信息：

$lang = array
(
       // 更改 'field' 的字段为实际字段的名字（例如：'email'）。 
	'field' => array
		(
			'required' => '名字不能为空',
			'alpha' => '只允许输入字母',
			'default' => '输入错误',
		),
);

使用 errors() 方法显示错误信息。默认情况下是返回带有定义的规则值的域名和键值的数组。

实例：回显自定义的错误信息。错误信息文件必须通过 errors() 方法传递。

$errors = $validation->errors();
// 假设定义了一个规则：add_rules('field', 'required') $errors array contains ('field' => 'required')
//
// 从错误信息文件获取错误信息
$errors = $validation->errors('form_errors')
// 假设 $lang 数组数组为：$lang = array('field' => array('required' => 'field may not be blank'))
// 那么 $errors 就会包括数组： ('field' => 'field may not be blank')

通过 as_array() 方法可以很容易获取到验证输入的数据。下面是一个非常有用的重新传递表单字段（re-populating form fields）例子：

// 假设表单字段原先定义在一个数组中，例如：$form = array('field_one' => '', 'field_two' => '')
// 在校验之后，如果有错误，我们需要重新传递表单字段的输入的信息
// 这里需要到 array 辅助函数来覆写原始数组
$form = arr::overwrite($form, $post->as_array());

相关描述和例子请看校验辅助函数。

本例假设一个控制器（application/controllers/welcome.php）中来校验表单：注意，下例中的表单使用 Kohana 的 form 辅助函数创建而成，当然你可以使用 HTML 代码完成并当作视图的一部分传递。更多信息请看这个例子。

public function testform()
{
    // 初始化表单字段名
    $form = array
    (
        'name'      => '',
        'number'    => '',
        'password'  => '',
        'code'      => '',
    );
 
    // 赋值表单的错误，这样会将相关表单字段键值的错误将存储
    $errors = $form;
 
    // 检测是否提交了表单，如果有执行校验
    if ($_POST)
    {
         // 实例化校验类给 $post，这样我们就不会覆写 $_POST 以影响结果 
        $post = new Validation($_POST);
 
         // 添加过滤器
        $post->pre_filter('trim', TRUE);
        $post->pre_filter('ucfirst', 'name');
 
        // 添加几条规则，检测指定的输入框是否为空，长度等
        $post->add_rules('name','required', 'length[3,20]', 'alpha');
        $post->add_rules('number', 'required', 'numeric', 'length[3,5]');
        $post->add_rules('password', 'required');
 
        // 在一个行或单独时我们可以使用不同的语法添加规则
        $post->add_rules('code',array('valid', 'numeric'));
        $post->add_rules('code','length[3]');
 
        // 添加一个回调来校验密码，这个是同一个控制器内定义的方法
        $post->add_callbacks('password', array($this, 'pwd_check'));
 
        // 如果通过规则检测
        if ($post->validate())
        {
            // Yes！所以的都通过校验
            echo 'Form validated and submitted correctly. <br />';
            // 那么，下面可以执行其他的动作
            die(html::anchor('welcome/testform', 'try it again'));
        }
        // 如果没有通过！我们还有校验错误，我们需要把它们在表单中显示出来
        else
        {
            // 重新载入表单字段
            $form = arr::overwrite($form, $post->as_array());
 
            // 传递错误字段，并且我们需要创建一个错误信息文件
            // Kohana 通过 errors() 方法调用错误信息文件传递错误信息
            $errors = arr::overwrite($errors, $post->errors('form_error_messages'));
        }
    }
 
    // 显示表单，如果没有任何错误，则会显示输入字段。这里使用 Kohana 的 form 辅助函数完成
    echo form::open();
    echo form::label('name', 'Your Name');
    echo form::input('name', ($form['name']));
    echo (empty ($errors['name'])) ? '' : $errors['name'];
    echo '<br />';
    echo form::label('number', 'Your Number');
    echo form::input('number', $form['number']);
    echo (empty ($errors['number'])) ? '' : $errors['number'];
    echo '<br />';
    echo form::label('password', 'Password');
    echo form::input('password', $form['password']);
    echo (empty ($errors['password'])) ? '' : $errors['password'];
    echo '<br />';
    echo form::label('code', 'Your code');
    echo form::input('code', $form['code']);
    echo (empty ($errors['code'])) ? '' : $errors['code'];
    echo '<br />';
    echo form::submit('submit', 'Send');
    echo '<br />';
    echo form::close();
}

在同一个控制器（application/controllers/welcome.php）自定义的回调函数：

public function pwd_check(Validation $post)
{
    // If add->rules validation found any errors, get me out of here!
    if (array_key_exists('password', $post->errors()))
        return;
 
    // 只校验密码是否为 '123'
    if ($post->password != '123')
    {
        // 添加校验错误，并使得 $post->validate() 返回为 FALSE
        $post->add_error( 'password', 'pwd_check');
    }
}

错误信息文件被放在 application/i18n/en_US/form_error_messages.php

<?php defined('SYSPATH') or die('No direct access allowed.');
 
$lang = array
(
'name' => Array
    (
        'required' => 'The name cannot be blank.',
        'alpha' => 'Only alphabetic characters are allowed.',
        'length' => 'The name must be between three and twenty letters.',
        'default' => 'Invalid Input.',
    ),
'number' => Array
    (
        'required' => 'The number cannot be blank.',
        'numeric' => 'Only numbers are allowed.',
        'length' => 'The number must be between three and five numerals.',
        'default' => 'Invalid Input.',
    ),
'code' => Array
    (
        'numeric' => 'Only numbers are allowed.',
        'length' => 'The code must be exactly three numerals.',
        'default' => 'Invalid Input.',
    ),
'password' => Array
    (
        'required' => 'You must supply a password.',
        'pwd_check' => 'The password is not correct.',
        'default' => 'Invalid Input.',
    ),
);

控制器代码：

// 使用 Kohana upload 辅助函数
$_FILES = Validation::factory($_FILES)
	->add_rules('picture', 'upload::valid', 'upload::type[gif,jpg,png]', 'upload::size[1M]');
 
if ($_FILES->validate())
{
	// 模板文件名
	$filename = upload::save('picture');
 
	// 图片大小，锐化，保存图片
	Image::factory($filename)
		->resize(100, 100, Image::WIDTH)
		->save(DOCROOT.'media/pictures/'.basename($filename).'.jpg');
 
	// 移除临时文件
	unlink($filename);
 
	// 跳转到 账户 页面
	url::redirect('account/information');
}

使用 ORM 的校验方法校验并保存数据到 ORM 模型中

控制器：

// 加载一个新用户
$user = ORM::factory('user');
 
$_POST
    ->add_rules('email', 'required', 'length[5,127]', 'valid::email')
    ->add_rules('password', 'required', 'length[5,127]')
    ->add_rules('password_confirm', 'matches[password]')
    ->add_callbacks('email', array($user, 'unique_email'));
 
if ($_POST->validate())
{
    foreach ($_POST->as_array() as $key => $val)
    {
        // 设置数据
        $user->$key = $val;
    }
 
    // 保存用户
    $user->save();
 
    // 跳转到 用户 页面
    url::redirect('users/details/'.$user->id);
}