how to use

如何使用

这里使用像 Yii 验证类似的配置规则： 每条规则可以针对多个字段，但是只能有一个验证器

如果你喜欢类似Laravel方式的配置规则，也是可以的。请直接参考下一篇文档

方式1: 直接使用类 Validation

需要快速简便的使用验证时，可直接使用 Inhere\Validate\Validation

use Inhere\Validate\Validation;

class SomeController
{
    public function demoAction()
    {
        $v = Validation::check($_POST,[
            // add rule
            ['title', 'min', 40],
            ['freeTime', 'number'],
        ]);

        if ($v->isFail()) {
            var_dump($v->getErrors());
            var_dump($v->firstError());
        }

        // $postData = $v->all(); // 原始数据
        $safeData = $v->getSafeData(); // 验证通过的安全数据

        $db->save($safeData);
    }
}

方式2: 继承类 Validation

创建一个新的class，并继承 Inhere\Validate\Validation。用于一个（或一系列相关）请求的验证, 相当于 laravel 的 表单请求验证

此方式是最为完整的使用方式，可以配置规则，设置字段翻译，设置自定义的错误消息等

use Inhere\Validate\Validation;

class PageRequest extends Validation
{
    public function rules()
    {
        return [
            // 字段必须存在且不能为空
            ['tagId,title,userId,freeTime', 'required'],
            
            // 4<= tagId <=567
            ['tagId', 'size', 'min'=>4, 'max'=>567, 'filter' => 'int'], 
            
            // title length >= 40. 注意只需一个参数的验证，无需加 key, 如这里的 40
            ['title', 'min', 40, 'filter' => 'trim'],
 
            // 大于 0
            ['freeTime', 'number'],
 
            // 含有前置条件
            ['tagId', 'number', 'when' => function($data) {
                return isset($data['status']) && $data['status'] > 2;
            }],
            
            // 在验证前会先过滤转换为 int。并且仅会在指明场景名为 'scene1' 时规则有效
            ['userId', 'number', 'on' => 'scene1', 'filter' => 'int'],
            ['username', 'string', 'on' => 'scene2', 'filter' => 'trim'],
            
            // 使用自定义正则表达式
            ['username', 'regexp' ,'/^[a-z]\w{2,12}$/'],
            
            // 自定义验证器，并指定当前规则的消息
            ['title', 'custom', 'msg' => '{attr} error msg!' ], 
            
            // 直接使用闭包验证
            ['status', function($status) { 
                if (is_int($status) && $status > 3) {
                    return true;
                }
                return false;
            }],
            
            // 标记字段是安全可靠的 无需验证
            ['createdAt, updatedAt', 'safe'],
        ];
    }
    
    // 定义不同场景需要验证的字段。 
    // 功能跟规则里的 'on' 类似，两者尽量不要同时使用，以免混淆。
    public function scenarios(): array
    {
        return [
            'create' => ['user', 'pwd', 'code'],
            'update' => ['user', 'pwd'],
        ];
    }

    // 定义字段翻译
    public function translates()
    {
        return [
          'userId' => '用户Id',
        ];
    }

    // 自定义验证器的提示消息, 默认消息请看 {@see ErrorMessageTrait::$messages}
    public function messages()
    {
        return [
          'required' => '{attr} 是必填项。',
          // 可以直接针对字段的某个规则进行消息定义
          'title.required' => 'O, 标题是必填项。are you known?',
        ];
    }
    
    // 添加一个验证器。必须返回一个布尔值标明验证失败或成功
    protected function customValidator($title)
    {
        // some logic ...
        // $this->getRaw('field'); 访问 data 数据

        return true; // Or false;
    }
}

• 使用

// 验证 POST 数据
$v = PageRequest::check($_POST);

// 验证失败
if ($v->isFail()) {
    var_dump($v->getErrors());
    var_dump($v->firstError());
}

// 验证成功 ...
$safeData = $v->getSafeData(); // 验证通过的安全数据
// $postData = $v->all(); // 原始数据

$db->save($safeData);

方式3: 使用trait ValidationTrait

创建一个新的class，并使用 Trait Inhere\Validate\ValidationTrait。

此方式是高级自定义的使用方式, 可以方便的嵌入到其他类中。

如下，嵌入到一个数据模型类中, 实现一个简单的模型基类，添加数据库记录前自动进行验证

class DataModel
{
    use \Inhere\Validate\ValidationTrait;

    protected $data = [];

    protected $db;

    /**
     * @param array $data
     * @return $this
     */
    public function load(array $data)
    {
        $this->data = $data;

        return $this;
    }

    public function create()
    {
        if ($this->validate()->isFail()) {
            return false;
        }

        return $this->db->insert($this->getSafeData());
    }
}

使用：

// on model class
class UserModel extends DataModel
{
    public function rules()
    {
        return [
            ['username, passwd', 'required'],
            ['passwd', 'compare', 'repasswd', 'on' => 'create']
            ['username', 'string', 'min' => 2, 'max' => 20, 'on' => 'create' ],
            ['id', 'number', 'on' => 'update' ], // 仅作用于场景 update
            ['createdAt, updatedAt', 'safe'],
        ];
    }
}

// on controller action ...
class UserController 
{
    // in action
    // @api /user/add
    public function addAction()
    {
        $model = new UserModel;
        // 载入提交数据并设定场景为: create
        $model->load($_POST)->atScene('create');

        if (!$ret = $model->create()) {
            exit($model->firstError());
        }

        echo "add success: userId = $ret";
    }
}