README

使用说明

安装 composer require zms/validate
环境 php7+
该文档为使用说明和 AI 投喂文档
适用于于2026年6月12日以及之后的包

类验证器说明

用法:新建验证类且继承Zms\Validate\ValidateAbstract

<?php
declare(strict_types=1);

use Zms\Validate\ValidateAbstract;
use \Zms\Validate\Type;

/**
 * 类验证器示例
 */
class TestValidate extends ValidateAbstract {

    /**
      * @var 空值是否跳过验证，空值包括空字符串，null,空数组
      */
    protected $emptySkip = true;

    /**
     * 结果中需要排除的字段，设置后获取的验证安全数据将不包含数据
     * @var string[]
     */
    protected $exclude = ['id'];
    /**
     * 数据验证前事件
     * @param array $data 传入的原始验证数据
     * @return array 返回值为最终要验证的数据
     */
    protected function beforeValidate(array $data) : array
    {
        return parent::beforeValidate($data);
    }


    /**
     * 验证数据字段的名称,比如验证数据终端name时,变量代码就是{label}的值就是'名称'
     * @return array
     */
    public function labels() : array
    {
        return [
            'id'=>'ID',
            'name'=>'名称',//支持['user'=>['name'=>'张三']]在labels中字段表示为'user.name'=>'名称'
        ];
    }


    /**
     * 验证规则
     *
     * @return array
     */
    public function rules() : array
    {
        /**
         * 每一个验证规则第一个元素为要验证的数据名称
         * 每一个验证规则第二个元素为验证规则
         * 每一个验证规则第三个元素开始为每个验证规则的单独参数,如Type::INT后面加上,'min'=>0,'max'=>10,代表最小验证值和最大验证值
         */
        return  [
            ['id',Type::INT],//当第一个参数为字符串时，代表的是单个数据字段使用这个验证规则,支持['user'=>['name'=>'张三']]在规则中字段表示为user.name
            [['id','name'],Type::REQUIRED],//当第一个参数为数组时，代表的是多个数据字段使用这个验证规则
            ['name','nameValidate'],//代表使用当前类的usernameValidate方法校验
            ['name',function($value, $find, $data){//这是回调函数验证示例，本质上和方法验证器是一样的
                if($value){
                    return $value;
                }
                $this->addError($find,'昵称验证失败');
                return null;
            }]
        ];
    }


   /**
     * 这是方法验证器的示例
     * @param mixed $value 要验证的值
     * @param self $find 验证数据的字段名
     * @param array $data 所有需要验证的数据
     * @return mixed|null
     */
    public function nameValidate($value, $find, $data) {
        if($value){
            return $value;//验证通过,返回数据
        }
        $this->addError($find,'数据验证失败');
        return null;//验证失败必须返回null
    }


    /**
      * 条件验证
      * @param string $find 正在验证中的字段
      * @param array $data  要验证的全部数据
      * @return bool 返回true代表需要验证该数据 返回false代表跳过此字段
      */
    public function where(string $find,array $data) : bool
    {
     return parent::where($find,$data); // TODO: Change the autogenerated stub
    }

    /**
      * 验证后事件
      * @param array $data 原始验证数据
      * @param array $safe 验证后的数据
      * @return array 返回的数据代表最终验证完成的数据
      */
    protected function afterValidate(array $data,array $safe) : array
    {
     return parent::afterValidate($data,$safe); // TODO: Change the autogenerated stub
    }
}

//验证使用示例
$validate=new TestValidate();
$validate->setData([]);//要验证的数据
//$validate->setScene('add');//验证场景
//$validate->setFields(['id','name']);//指定验证的字段,设置后场景将无效
$validate=$validate->validate();
if ($validate->isFail()) {//验证失败
   $validate->getErrorList();//回去错误信息
} else {//验证成功
   $validate->getSafeData();//获取数据
}

验证规则

通用参数 | 参数 | 类型 | 参数描述 | 默认值 | | ----- | ------ | ---------------- | --------------- | | on | string[] | 验证场景,根据场景指定验证数据 | [] | | emptySkip | bool | 如果未传值或值为 null 时是否可以跳过验证 |false | | default | any | 当值为空值，如 null,'',[]等值时使用的默认值，未设置则不填充 | |

01:Type::REQUIRED

必填验证器

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的提示	{label}不能为空

02:Type::RequiredHtmlValidate

输入的内容为 HTML,判断是否有有效内容,也是必填验证器的一种不过

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的提示	{label}不能为空

03:Type::REQUIRED_CHOOSE

必选验证器

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的提示	请选择{label}

04:Type::REQUIRED_UPLOAD 必传文件验证器错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的提示	请上传{label}

05:Type::STRING

字符串验证器

错误信息可用变量:{label},{max},{mix},{value}

参数	类型	参数描述	默认值
max	int	最大长度	0，代表不限制
maxError	string	最大长度验证失败提示	{label}最多不能超过{max}个字
min	int	最小长度	0，代表不限制
minError	string	最小长度验证失败提示	{label}不能少于{min}个字
error	string	数据类型未通过验证错误提示	{label}不是有效的 string 类型数据

06:Type::IN

IN 验证器，验证值是否包含,和 php 函数 in_array 一致

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
enums	string[]或 number[]	包含的数据	[]
error	string	验证失败时的错误提示	{label}选择错误
strict	bool	in_array 是否启用严格模式	false

07:Type::EXCLUDE_IN

和 Type::IN 相反,这是一个禁止选择的选项验证

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
enums	string[]或 number[]	禁止包含的数据	[]
error	string	验证失败时的错误提示	{label}选择错误
strict	bool	in_array 是否启用严格模式	false

08:Type::MULTI_SELECTOR

多选验证器

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
enums	string[]或 number[]	禁止包含的数据	[]
allowOther	bool	是否允许包含 enums 之外的值	false
allowOtherError	string	出现非法数据是的错误提示	{label}中含有无效的选项
error	string	验证失败时的错误提示	{label}选择错误
strict	bool	in_array 是否启用严格模式	false
excludeInvalid	bool	allowOther 为 true 时出现非法值是否过滤	true

09:Type::IDENTITY_NUMBER

身份证号码验证器

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的错误提示	{label}不是有效的身份证号码
strict	bool	是否启用严格模式,false 时将只会验证身份证的号码长度是否符合要求	false

10:Type::URL

URL 验证器

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的错误提示	{label}不是有效的 URL 地址

11:Type::POINT

坐标验证器,value 结构为['lng'=>'','lat'=>''],验证是否是一个正确的点坐标

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的错误提示	{label}不是有效的坐标

12:Type::EMAIL

邮箱验证器，验证是否是一个有效的邮箱地址

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的错误提示	{label}不是有效的邮箱地址

13:Type::IP

IP 验证器，验证是否是一个有效的 IP 地址

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
type	ipv4 或 ipv6	指定验证 IP 类型，空值为不限	''
typeError	string	类型验证失败时的提示	{label}不是{type}类型 IP 地址
error	string	验证失败时的错误提示	{label}不是有效的 IP

14:Type::PHONE,Type::MOBILE

Type::PHONE 和 Type::MOBILE 都是手机号验证器，完全一样,只按中国 11 位手机号的规则验证,不考虑区号

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的错误提示	{label}不是有效的手机号码

15:Type::LIST

列表验证器,数据类型是 array，但要求符合列表

错误信息可用变量:{label},{count},{value},{mix},{max}

参数	类型	参数描述	默认值
type	string	列表类型，当设置为 number 时数据类型为 number[],当设置 string 时数据类型为 string[],否则只要数据为列表(其他语言的数组)即可
typeError	string	列表类型验证失败提示
count	int	是否指定列表长度，不设置或 0 则不限制	0
countError	string	列表长度验证失败的错误提示	{label}数量只能是{count}个
min	int	列表最小元素数量，不设置或 0 则不限制	0
minError	string	列表最小长度验证失败的错误提示	{label}不能少于{min}个
max	int	列表最大元素数量，不设置或 0 则不限制	0
maxError	string	列表最大长度验证失败的错误提示	{label}不能超过{max}个
enums	any[]	列表值是否只能是 enums 限定的值,不设置或空值则不限制	[]
enumsError	string	限定值验证失败提示	{label}包含的选择项未通过验证
split	string	当验证值为字符串时，是否先通过 split 字符把字符串分给为列表再验证，空值为不分割
error	string	验证失败时的错误提示	{label}不符合要求

16:Type::ARRAY

验证数据是否是数组

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的错误提示	{label}数据类型错误

17:Type::MATCH

正则验证器

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
pattern	string	正则表达式	{label}验证失败
not	bool	是否结果取反	false
error	string	验证失败时的错误提示	{label}数据类型错误

18:Type::NUMBER

数字验证器

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
min	int 或 float	数字最小值,null 为不限制	null
minError	string	数字最小值验证未通过错误提示	{label}不能小于{min}
max	int 或 float	数字最大值,null 为不限制	null
maxError	string	数字最大值验证未通过错误提示	{label}不能大于{max}
precision	int	小数精度,限定小数位数,null 为不限制	null
precisionError	string	精度验证失败错误信息	{label}只能精确到{precision}位小数
error	string	验证失败时的错误提示	{label}必须是数字

19:Type::INT

继承自数字验证器,验证数字是否为整数

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
min	int 或 float	数字最小值,null 为不限制	null
minError	string	数字最小值验证未通过错误提示	{label}不能小于{min}
max	int 或 float	数字最大值,null 为不限制	null
maxError	string	数字最大值验证未通过错误提示	{label}不能大于{max}
error	string	验证失败时的错误提示	{label}必须是整数

20:Type::MONEY

验证值是否是金额,最多精确到分

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
min	int 或 float	金额最小值,null 为不限制	null
minError	string	金额最小值验证未通过错误提示	{label}不能小于{min}
max	int 或 float	金额最大值,null 为不限制	null
maxError	string	金额最大值验证未通过错误提示	{label}不能大于{max}
error	string	验证失败时的错误提示	{label}不是有效的金额

21:Type::QQ

验证值是否是 QQ 号

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的错误提示	{label}不是有效的 QQ

22:Type::DATETIME

验证值是否是日期时间

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
format	string	验证日期时间格式	Y-m-d H:i:s
formatError	string	验证格式失败的错误提示	{label}时间格式不符合要求
error	string	验证失败时的错误提示	{label}不是有效时间

23:Type::DateValidate

验证值是否是日期,继承自 Type::DATETIME

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
format	string	验证日期时间格式	Y-m-d
formatError	string	验证格式失败的错误提示	{label}时间格式不符合要求
error	string	验证失败时的错误提示	{label}不是有效时间

24:Type::DATE_FORMAT

时间格式验证

错误信息可用变量:{label},{value}

output是把收到的时间转为指定格式，timestamp是收到的时间转为10位时间戳，如果都设置了的话就以timestamp为准

参数	类型	参数描述	默认值
output	?string	是否把日期输出为指定的格式,null 不转	null
timestamp	bool	是否把日期输出为 10 位时间戳,优先级大于 output	false
completion	string	设置后输出之前将不完整的时间补全为完整的时间格式，比如completion设置我要求的时间是Y-m-d H:i,但收到的时间是Y-m，那么我就需要补全-d H:i,而-d H:i则来自当前时间
error	string	验证失败时的错误提示	{label}不是有效时间

25:Type::LIST_INTERSECT

列表交集,输入值为列表,和 enums 进行比对

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
enums	any[]	限定的数据，如[1,2,3,4,5,'a','b']	null
strict	bool	是否开启严格模式，true:当输入列表存在 enmus 之外的值时验证失败,false 则过滤且验证成功	false
error	string	验证失败时的错误提示	{label}不是有效时间

26:Type::JSON

判断输入的内容是否为 JSON 字符串

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的错误提示	{label}不是有效的数据格式

27:Type::ACCEPTED

确认验证器,主要用于协议勾选，当值为'ok', 'yes', 1, '1', true, 'true'其中任意一个时视为勾选了协议，验证通过，否则验证失败

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的错误提示	请先确认{label}

28:Type::ZIPCODE

中国邮政编号验证

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
error	string	验证失败时的错误提示	{label}不是有效的邮政编码

29:Type::VIOLATE

违禁词检测

错误信息可用变量:{label},{value},{words}(匹配到的违禁词)

检测内容:这是大傻逼一个，非法词:傻逼model=warn抛出警告，验证未通过，model=replace，通过验证，获取数据:这是大**一个

参数	类型	参数描述	默认值
words	string[]	设定的违禁词	[]
model	warn,replace	warn 时匹配到违禁词则验证失败且抛出错误信息,replace 时则把违禁词用同等数量的*号替换做脱敏处理，且验证通过	warn
error	string	验证失败时的错误提示	{label}中含有非法的词汇,{words}

30:Type::DOMAIN

域名验证

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
clear_ending	bool	是否去掉结尾的/符号	true
scheme	string[]	合法的协议	['http', 'https']
port	bool	是否允许带端口	true
ip	bool	域名是否允许时 IP	true
error	string	验证失败时的错误提示	{label}不是有效的域名

31:Type::BANKCARD

银行卡号码验证

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
strict	bool	是否开启严格验证,true 时仅允许 4242424242424242424 这类格式,false 时允许 4242 4242 4242 4242 424 或 4242-4242-4242-4242-424 这类银行卡格式	false
luhn	bool	是否进行 luhn 算法校验	true
convert	bool	是否统一把银行号号码转为纯数字模式输出	true
error	string	验证失败时的错误提示	{label}未通过验证

32:Type::COMPARE

字段比对，常用语密码确认

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
find	string	要对比的字段
error	string	两个值不一致时的失败提醒	{label}和{这里是比对值对应 label}不一致

33:Type::DEFAULT

默认值，当没有值是的默认填充值

错误信息可用变量:{label},{value}

参数	类型	参数描述	默认值
value	any	默认值

34:Type::SAFE

数据安全,只要存在此验证规则就代表值是安全的

函数验证示例

<?php
use function Zms\Validate\validate;
$rules=[];//验证规则和类验证器一样，但不支持方法验证和回调验证
$data=[];//要验证的数据
$label=[];//字段描述，和类验证器一样
$scene='created';//验证场景,可选

$result=validate($rules, $data, $label, $scene);
if(is_string($result)){
    echo $result;//string 验证失败,且这是第一条错误信息
}else{
    print_r($result);//array 验证成功后获得的数据
}

指定字段函数验证示例

<?php
use function Zms\Validate\specificValidate;
$rules=[];//验证规则和类验证器一样，但不支持方法验证和回调验证
$data=[];//要验证的数据
$finds=['name'];//需要验证的字段,场景将无效
$label=[];//字段描述，和类验证器一样

$result=specificValidate($rules, $data,$finds, $label);
if(is_string($result)){
    echo $result;//string 验证失败,且这是第一条错误信息
}else{
    print_r($result);//array 验证成功后获得的数据
}

hyperf 注解验证

安装注解验证包 composer require zms/hyperf-validate-annotations

<?php
declare(strict_types);

use Zms\HyperfValidateAnnotations\Validate;

class ApiController{
   #[
        Validate(class: TestValidate::class)//是类验证示例
    ]
    public function created(): ResponseInterface
    {
        $data = $this->request->getParsedBody();
        return Response::Success('数据验证成功', $data);
    }

    #[
        Validate(//这是注解验证示例，规则和labels和类验证器一样，但不支持方法验证器和回调验证器
            rules: [
                ['id', Type::REQUIRED, 'error' => '操作异常'],
                [['title'], Type::REQUIRED],
                [['title'], Type::STRING, 'min' => 2, 'max' => 80],
                ['remark', Type::STRING, 'max' => 300],
                ['preset', Type::STRING],
            ],
            labels: [
                'title'  => '会话名称',
                'remark' => '会话备注',
                'preset' => '预置参数',
            ]
        ),
    ]
    public function updated(): ResponseInterface
    {
        $data = $this->request->getParsedBody();
        return Response::Success('数据验证成功', $data);
    }
}

Validate 注解参数

参数	类型	描述	必填
method	string	指定请求类型时触发注解验证	否，默认 POST
class	string	验证类	和 rules 二选一
rules	array	验证规则	和 class 二选一
labels	array	字段描述	使用 rules 模式时有效
fields	string[]	指定验证的字段,优先级大于 scene,设置了 fields 那么将不会使用 scene	false
scene	string	验证场景	可选，使用 class 模式时有效

hyperf 扩展验证规则

1:类验证中增加方法验证器或回调验证
2:新建验证抽象,如下:

<?php
declare(strict_types=1);
namespace Zms;
/**
 * 新建验证抽象继承\Zms\Validate\ValidateAbstract
 * 然后验证类继承由\Zms\Validate\ValidateAbstract改为此抽象
 */
class NewsValidateAbstract extends \Zms\Validate\ValidateAbstract{
    /**
     * 重新验证映射
     * @return array
     */
    public function verifyMapping() : array{
     $verify = parent::verifyMapping();
     $verify['text']=TextValidate::class;//TextValidate需要继承\Zms\Validate\Rule\RuleAbstract且实现validate
     return $verify;
    }
}

附录

>php严格意义上的数组不存在或不规范，文档中的列表其实指的是属数组，如[1,2,3],['a','b','c']或[1,2,'a'],也就是其他语言中的数组，对于[1,'mobile'=>'123']是数组但不是列表，PHP本身没有这个区分，这里是为了区分开的自定义概念,is_array无法区分，已实现通过\Zms\Unit\Is::list来区分是否是列表

zms / validate

Maintainers

Package info

Statistics

Security

README

使用说明

类验证器说明

验证规则

函数验证示例

指定字段函数验证示例

hyperf 注解验证

hyperf 扩展验证规则

附录