inhere / php-validate
generic data validate, filter library of the php
Installs: 71 221
Dependents: 14
Suggesters: 31
Security: 0
Stars: 257
Watchers: 13
Forks: 33
Open Issues: 15
Requires
- php: >8.1.0
- toolkit/stdlib: ~2.0
Requires (Dev)
- phpunit/phpunit: ^9.5
- dev-master
- v3.0.0
- 2.x-dev
- v2.8.5
- v2.8.4
- v2.8.3
- v2.8.2
- v2.8.1
- v2.8.0
- v2.7.4
- v2.7.3
- v2.7.2
- v2.7.1
- v2.7.0
- 2.6.x-dev
- v2.6.6
- v2.6.5
- v2.6.4
- v2.6.3
- v2.6.2
- v2.6.1
- v2.6.0
- v2.5.3
- v2.5.2
- v2.5.1
- v2.5.0
- v2.4.12
- v2.4.11
- v2.4.10
- v2.4.9
- v2.4.8
- v2.4.7
- v2.4.6
- v2.4.5
- v2.4.4
- v2.4.3
- v2.4.2
- v2.4.1
- v2.4.0
- v2.3.5
- v2.3.4
- v2.3.3
- v2.3.2
- v2.3.1
- v2.3.0
- v2.2.1
- v2.2.0
- v2.1.1
- v2.1.0
- v2.0.2
- v2.0.1
- v2.0.0
- 1.x-dev
- v1.3.3
- v1.3.2
- v1.3.1
- v1.3.0
- v1.2.3
- v1.2.2
- v1.2.1
- v1.2.0
- v1.1.0
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- dev-dependabot/composer/phpunit/phpunit-tw-9.5or-tw-10.0
This package is auto-updated.
Last update: 2024-11-30 01:52:22 UTC
README
一个简洁小巧且功能完善的php验证、过滤库。
- 简单方便,支持添加自定义验证器
- 支持前置验证检查, 自定义如何判断非空
- 支持将规则按场景进行分组设置。或者部分验证
- 支持在进行验证前对值使用过滤器进行净化过滤内置过滤器
- 支持在进行验证前置处理和后置处理独立验证处理
- 支持自定义每个验证的错误消息,字段翻译,消息翻译,支持默认值
- 支持基本的数组检查,数组的子级(
'goods.apple'
)值检查, 通配符的子级检查 ('users.*.id' 'goods.*'
) - 方便的获取错误信息,验证后的安全数据获取(只会收集有规则检查过的数据)
- 已经内置了大量的常用的验证器内置验证器
- 规则设置参考
yii
,laravel
,Respect/Validation
- 独立的过滤器
Inhere\Validate\Filter\Filtration
,可单独用于数据过滤
两种规则配置方式
validate 同时支持两种规则配置方式,对应了两种规则的收集解析策略。
多字段单规则
Validation|RuleValidation
: 每条规则中,允许多个字段,但只能有一个验证器。 (规则配置类似于Yii)
配置示例: (本文档的示例都是这种)
[ ['tagId,userId,name,email,freeTime', 'required', ...], // ... ... ];
单字段多规则
FieldValidation
: 每条规则中,只能有一个字段,但允许多个验证器。 (规则配置类似于Laravel)FieldValidation
: 不支持验证器each
配置示例:
[ ['field', 'required|string:5,10|...', ...], // ... ... ]
更多配置示例请参看 像Laravel一样配置
项目地址
安装
composer require inhere/php-validate # or # composer require inhere/php-validate ^3.0
注意
master
分支是要求php8.1+
的(推荐使用)2.x
分支是支持php7.1+
,但是基本上不再维护。1.x
分支是支持php5的代码分支,但是基本上不再维护。
立即使用
方式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 { # 进行验证前处理,返回false则停止验证,但没有错误信息,可以在逻辑中调用 addError 增加错误信息 public function beforeValidate(): bool { return true; } # 进行验证后处理,该干啥干啥 public function afterValidate(): bool { return true; } public function rules(): array { 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(): array { return [ 'userId' => '用户Id', ]; } // 自定义验证器的提示消息, 默认消息请看 {@see ErrorMessageTrait::$messages} public function messages(): array { return [ // 使用验证器名字指定消息 'required' => '{attr} 是必填项。', // 可以直接针对字段的某个规则进行消息定义 'title.required' => 'O, 标题是必填项。are you known?', ]; } // 添加一个验证器。必须返回一个布尔值标明验证失败或成功 protected function customValidator($title): bool { // 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(): array { 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"; } }
添加自定义验证器
底层调用验证器是支持:
- 一个闭包
- 一个函数名称
- 一个当前验证类的方法名
- 在继承了
Inhere\Validate\Validation
的子类添加验证方法. 请看上面的 使用方式1
- 在继承了
- 一个通过
Validation->addValidator()
添加的临时验证器 - 一个通过
Validator\UserValidators::set
注册的全局验证器 - 一个实现了
Validator\ValidatorInterface
的对象 - 一个可调用的对象(有
__invoke
方法)
注意: 写在当前类里的验证器方法必须带有后缀
Validator
, 以防止对内部的其他的方法造成干扰
示例
$v = Validation::make($_POST,[ // add rule ['title', 'min', 40], ['freeTime', 'number'], ['title', 'checkTitle'], ]) ->addValidator('checkTitle',function($title) { // 第一个参数是字段值。最后一个参数总是 $data // some logic ... return true; // 成功返回 True。验证失败,返回 False. }, '{attr} default message!') ->validate();
直接写闭包进行验证 e.g:
['status', function($status) { // 第一个参数是字段值。最后一个参数总是 $data if ($status > 3) { return true; } return false; }]
定义一个闭包验证类进行验证,这种方法能提高验证方法的复用性
别忘了继承
\Inhere\Validate\Validator\AbstractValidator
,和实现必须方法validate
class AdemoValidator extends \Inhere\Validate\Validator\AbstractValidator { public function validate($value, $data): bool { if ($value == 1) { return true; } return false; } } // 使用 ['status', new AdemoValidator()],
验证前置/后置处理
- 方式1: 在
Validation
中
该方法与
onBeforeValidate
&onAfterValidate
有冲突
use Inhere\Validate\Validation; class PageValidation extends Validation { # 进行验证前处理,返回false则停止验证,但没有错误信息,可以在逻辑中调用 addError 增加错误信息 public function beforeValidate(): bool { return true; } # 进行验证后处理,该干啥干啥 public function afterValidate(): bool { return true; } }
- 方式2:
onBeforeValidate
&onAfterValidate
use Inhere\Validate\Validation; $v = Validation::make(['name' => 'inhere'], [ ['name', 'string', 'min' => 3, 'filter' => 'trim|upper'] ]); $v->onBeforeValidate(function (Validation $v) { return true; }); $v->onAfterValidate(function (Validation $v) { }); $v->validate();
一个完整的规则示例
一个完整的规则示例, 包含了所有可添加的项。
注意:
- 每条规则的第一个元素必须是 要验证的字段(可以同时配置多个,可以是数组. type:
string|array
) - 第二个元素必须是一个验证器(字符串,闭包,可回调的对象或数组. type:
string|Closure|callable
) - 后面紧跟着 是验证器可能需要的参数信息 (若验证器需要的参数只有一个,则参数无需带key)
- 然后就是其他选项配置(
msg
,on
,filter
, ...)
// a full rule [ // basic validate setting 'field0,field1,...', 'validator', 'arg0', 'arg1', ..., // some extended option settings 'skipOnEmpty' => 'bool', 'msg' => 'string|array', 'default' => 'mixed', 'on' => 'string|array' 'isEmpty' => 'callback(string|closure)', 'when' => 'callback(string|closure)', 'filter' => 'callback(string|array|closure)' ]
字段验证器
FieldValidation
的配置类似,只是 只有一个字段,而验证器允许有多个
规则选项设置
除了可以添加字段的验证之外,还有一些特殊关键词可以设置使用,以适应各种需求。
default
-- 设置字段的默认值
给一个或多个字段设置一个默认值。
['page', 'number', 'default' => 1], ['pageSize', 'number', 'default' => 15],
NOTICE: 默认值也会被验证器验证
msg
-- 设置错误提示消息
设置当前规则的错误提示消息, 设置了后就不会在使用默认的提示消息。
['title', 'customValidator', 'msg' => '{attr} error msg!' ], // 指定当前规则的消息 // o, 可以是数组哦 :) ['tagId,title,userId,freeTime', 'required', 'msg' => [ 'tagId' => 'message ...', 'userId' => 'message 1 ...', ]],
on
-- 设置规则使用场景
如果需要让定义的规则在多个类似情形下重复使用,可以设置规则的使用场景。在验证时也表明要验证的场景
// 在继承了 Validation 的子类 ValidationClass 中 ... public function rules(): array { return [ ['title', 'required' ], ['userId', 'number', 'on' => 'create' ], ['userId', 'int', 'on' => 'update' ], ['name', 'string', 'on' => 'create,update' ], ]; }
使用:
如,在下面指定了验证场景时,将会使用上面的第 1,3,4 条规则. (第 1 条没有限制规则使用场景的,在所有场景都可用)
// ... $valid = ValidationClass::make($_POST)->atScene('update')->validate(); // ...
when
-- 规则的前置条件
只有在先满足了(
when
)前置条件时才会验证这条规则
如在下面的例子中,检查到第二条规则时,会先执行闭包(when
),
当其返回 true
验证此条规则,否则不会验证此条规则
// 在继承了 Validation 的子类中 ... public function rules(): array { return [ ['title', 'required' ], ['tagId', 'number', 'when' => function($data) { return isset($data['status']) && $data['status'] > 2; }], ]; }
skipOnEmpty
-- 为空是否跳过验证
当字段值为空时是否跳过验证,默认值是 true
. (参考自 yii2)
'required*' 规则不在此限制内.
如,有一条规则:
['name', 'string']
提交的数据中 没有 name
字段或者 $data['name']
等于空都不会进行 string
验证;
只有当 $data['name']
有值且不为空 时才会验证是否是 string
如果要想为空时也检查, 请将此字段同时加入 required
规则中.
['name', 'required' ] ['name', 'string' ]
或者也可以设置 'skipOnEmpty' => false
:
['name', 'string', 'skipOnEmpty' => false ]
如何确定值为空 关于为空
isEmpty
-- 是否为空判断
是否为空判断, 这个判断作为 skipOnEmpty
的依据. 默认使用 Validators::isEmpty
来判断.
你也可以自定义判断规则:
['name', 'string', 'isEmpty' => function($value) { return true or false; }]
自定义 isEmpty 验证时,应留意 $value 是否为 ArrayValueNotExists 实例
['users.*.id', 'each', 'required', 'isEmpty' => function($value) { // each value must be verified foreach ($value as $item) { if ($item instanceof \Inhere\Validate\Exception\ArrayValueNotExists) { return true; } // your code here ... }]
filter
-- 使用过滤器
支持在进行验证前对值使用过滤器进行净化过滤内置过滤器
['tagId,userId,freeTime', 'number', 'filter' => 'int'], ['field', 'validator', 'filter' => 'filter0|filter1...'], // 需要自定义性更高时,可以使用数组。 ['field1', 'validator', 'filter' => [ 'string', 'trim', ['Class', 'method'], ['Object', 'method'], // 追加额外参数。 传入时,第一个参数总是要过滤的字段值,其余的依次追加 'myFilter' => ['arg1', 'arg2'], // 直接使用闭包 function($val) { return str_replace(' ', '', $val); }, ]],
提示:
- 允许同时使用多个过滤器。字符串使用
|
分隔,或者配置为数组。 - 注意: 写在当前类里的过滤器方法必须带有后缀
Filter
, 以防止对内部的其他的方法造成干扰 - 通过类
Filtration
,可以独立使用过滤器功能 - php内置过滤器请参看 http://php.net/manual/zh/filter.filters.sanitize.php
场景验证
如果需要让定义的规则在多个类似情形下重复使用,可以设置规则的使用场景。 在验证时也表明要验证的场景
方式1
在继承类中使用 scenarios()
方法:
// 在继承了 Validation 的子类 ValidationClass 中 ... // 定义不同场景需要验证的字段。 // 功能跟规则里的 'on' 类似,两者尽量不要同时使用,以免混淆。 public function scenarios(): array { return [ 'create' => ['user', 'pwd', 'code'], 'update' => ['user', 'pwd'], ]; }
方式2
添加规则时配置 on
选项:
// 在继承了 Validation 的子类 ValidationClass 中 ... public function rules(): array { return [ ['title', 'required' ], ['userId', 'number', 'on' => 'create' ], ['userId', 'int', 'on' => 'update' ], ['name', 'string', 'on' => 'create,update' ], ]; }
验证使用
$v->setSecne('update')->validate();
选项设置
StopOnError
stopOnError
是否在出现第一个验证错误时就停止验证。
- 默认
true
, 总是只会拿到第一个错误,这样性能更好。 - 设置为
false
, 则会检查全部规则,拿到全部的验证错误。
$v->setStopOnError(false);
SkipOnEmpty
SkipOnEmpty
为空是否跳过验证, 默认true
(此时需配合required
验证不可为空)
$v->setSkipOnEmpty(false);
内置的过滤器
一些 php 内置的函数可直接使用。 e.g
trim|ucfirst
json_decode
md5
内置的验证器
/
分隔的验证器,表明功能是一样的,只是有不同的别名
safe
验证器,标记属性/字段是安全的
特殊验证器 用于标记字段是安全的,无需验证,直接加入到安全数据中。
比如我们在写入数据库之前手动追加的字段: 创建时间,更新时间。
['createdAt, updatedAt', 'safe']
一些补充说明
关于为空判断
字段符合下方任一条件时即为「空」
- 该值为
null
. - 该值为空字符串
''
- 该值为空数组
[]
- 该值为空对象 -- 空的
可数
对象 - 该值为没有路径的上传文件
关于布尔值
值符合下列的任意一项即认为是为bool值(不区分大小写)
- 是 "1"、"true"、"on" 和 "yes" (
TRUE
) - 是 "0"、"false"、"off"、"no" 和 "" (
FALSE
)
关于文件验证
文件验证时注意要设置文件信息源数据
$v = Validation::make($_POST, [ // [...], // some rules ... ]) ->setUploadedFiles($_FILES) ->validate(); // ...
提示和注意
- 请将
required*
系列规则写在规则列表的最前面 - 规则上都支持添加过滤器
- 验证大小范围
int
是比较大小。string
和array
是检查长度。大小范围 是包含边界值的 size/range
length
可以只定义min
或者max
值- 支持对数组的子级值验证
[ 'goods' => [ 'apple' => 34, 'pear' => 50, ], ]
规则:
['goods.pear', 'max', 30], //goods 下的 pear 值最大不能超过 30
- 支持对数组的子级值进行遍历验证
[ 'goods' => [ 'apple' => 34, 'pear' => 50, ], 'users' => [ ['id' => 34, 'name' => 'tom'], ['id' => 89, 'name' => 'john'], ] ]
['goods.*', 'each', 'number'], //goods 下的 每个值 都必须为大于0 的整数 // 写法是等效的 // ['goods', 'each', 'number'], //goods 下的 每个值 都必须为大于0 的整数 // 多维数组 ['users.*.id', 'each', 'required'], ['users.*.id', 'each', 'number', 'min' => 34], ['users.*.name', 'each', 'string', 'min' => 5],
- 对于带有通配符
*
的字段, 添加过滤器是无效的
一些关键方法API
设置验证场景
public function setScene(string $scene) public function atScene(string $scene) // setScene 的别名方法
设置当前验证的场景名称。将只会使用符合当前场景的规则对数据进行验证
进行数据验证
public function validate(array $onlyChecked = [], $stopOnError = null)
进行数据验证。 返回验证器对象,然后就可以获取验证结果等信息。
$onlyChecked
可以设置此次需要验证的字段$stopOnError
是否当出现一个验证失败就立即停止。 默认是true
添加自定义的验证器
public function addValidator(string $name, \Closure $callback, string $msg = '')
添加自定义的验证器。 返回验证器对象以支持链式调用
$name
自定义验证器名称$callback
自定义验证器。处理验证,为了简洁只允许闭包。$msg
可选的。 当前验证器的错误消息
判断验证是否通过
// 验证失败
public function isFail()
public function hasError() // isFail() 的别名方法
// 成功通过验证
public function isOk()
public function isPassed()
获取验证是否通过(是否有验证失败)。
获取所有错误信息
public function getErrors(): array
获取所有的错误信息, 包含所有错误的字段和错误信息的多维数组。 eg:
[ ['name' => 'field1', 'msg' => 'error Message1' ], ['name' => 'field2', 'msg' => 'error Message2' ], ... ]
同一个属性/字段也可能有多个错误消息,当为它添加了多个验证规则时。
得到第一个错误信息
public function firstError($onlyMsg = true)
$onlyMsg
是否只返回消息字符串。当为 false,返回的则是数组 eg:['name' => 'field', 'msg' => 'error message']
得到最后一个错误信息
public function lastError($onlyMsg = true)
$onlyMsg
是否只返回消息字符串。当为 false,返回的则是数组 eg:['name' => 'field', 'msg' => 'error message']
获取所有验证通过的数据
public function getSafeData(): array|\stdClass
获取所有 验证通过 的安全数据.
- 此数据数组只包含加入了规则验证的字段数据,不会含有额外的字段。(可直接省去后续的字段收集)
- 推荐使用此数据进行后续操作,比如存入数据库等。
注意: 当有验证失败出现时,安全数据
safeData
将会被重置为空。 即只有全部通过验证,才能获取到safeData
根据字段名获取安全值
public function val(string $key, $default = null) // getSafe() 的别名方法 public function getValid(string $key, $default = null) // getSafe() 的别名方法 public function getSafe(string $key, $default = null)
从 验证通过 的数据中取出对应 key 的值
获取所有原始数据
public function all(): array
获取验证时传入的所有数据
根据字段名获取原始数据的值
public function getRaw(string $key, $default = null)
从验证时传入的数据中取出对应 key 的值
代码示例
可运行示例请看 example
单元测试
phpunit
License
我的其他项目
- inhere/console 轻量且功能丰富的命令行应用, 控制台交互,工具库
- inhere/sroute 轻量且快速的HTTP请求路由库