Download the PHP package githusband/validation without Composer

English | 中文

Validation

简单，直观，客制化

目录

• Validation —— 一款 PHP 直观的数据验证器
  • 1. 简介
    • 1.1 特点
    • 1.2 一个例子
  • 2. 安装
  • 3. 开发
  • 4. 功能介绍
    • 4.1 方法及其标志
    • 4.2 正则表达式
    • 4.3 方法传参
    • 传参的几种方式
    • 参数类型
    • 4.4 自定义方法
    • 自定义方法的几种方式
    • 设置方法标志
    • 4.5 串联并联规则
    • 4.6 条件规则
      • When 条件规则
      • IF 条件规则
    • 4.7 无限嵌套的数据结构
      • 数组自身的规则
    • 4.8 可选字段
    • 4.9 特殊的验证规则
    • 4.10 客制化配置
      • 启用实体（重点）
    • 4.11 国际化
    • 4.12 验证全部数据
    • 4.13 错误信息模板
    • 4.14 错误信息格式
  • 附录 1 - 方法标志及其含义
  • 附录 2 - 验证完整示例
  • 附录 3 - 错误信息格式
    • 一维字符型结构
    • 一维关联型结构
    • 无限嵌套字符型结构
    • 无限嵌套关联型结构

Validation —— 一款 PHP 直观的数据验证器

Validation 用于对数据合法性的检查。 目标只有 10 个字 - 规则结构即是数据结构。

github 仓库

期待任何形式的贡献，让我们一起开发或优化 Validation！谢谢！

1. 简介

1.1 特点

• 一个字段对应一个验证规则集，一个规则集由多个验证规则和方法（函数）组成。
• 验证方法支持用标志代替，易于理解，简化规则。采用*, >, <, length> 等方法标志，比如 * 表示必要的

• 支持正则表达式

  👇 点击查看更多特性...
• 支持方法传参。如 @this 代表当前字段值
• 支持拓展方法
• 支持串联验证：一个参数多个方法必须全部满足
• 支持并联验证：一个参数多个规则满足其一即可
• 支持条件验证：条件满足则继续验证后续方法，不满足则表明该字段是可选的
• 支持无限嵌套的数据结构，包括关联数组，索引数组
• 支持特殊的验证规则
• 支持客制化配置。比如多个方法的分隔符号默认 |，可以改为其他字符，如 ;
• 支持国际化。默认英语，支持自定义方法返回错误信息
• 支持一次性验证全部数据(默认)，也可设置参数验证失败后立即结束验证
• 支持自定义错误信息，支持多种格式的错误信息，无限嵌套或者一维数组的错误信息格式
• 暂时想不到，想到了再给你们编。 🐶

1.2 一个例子

理论上，该工具是用于验证复杂的数据结构的，但如果你想验证单一字符串，也可以，例如

• 以上仅展示简单示例，实际上无论请求参数多么复杂，都支持一个验证规则数组完成验证。参考 附录 2 - 验证完整示例
• 规则写的太丑了？参考 4.10 客制化配置

2. 安装

3. 开发

如果你有想法优化开发本工具，以下将为你提供帮助：

在 src/Test 目录下已经内置了单元测试类 Unit.php 和 文档测试类 Readme.php 通过 Composer Script 调用它们。

克隆本项目后，请先加载项目的自动加载文件：

由于测试文件中使用了部分外部库，如 uuid, 我们不能简单地加载项目的自动加载文件，而需要下载外部库,

• 单元测试类

这里包含了所有功能的测试，只包含部分内置函数。 原则上修改代码后跑一遍单元测试，确保功能正常。

如果你已经安装 Docker，那么，你可以一次性测试多个 PHP 版本： PHP v5.6, PHP v7.4.33 和 PHP 最新版本

• 文档测试类

文档代码：1.2 一个例子

文档代码：附录 2 - 验证完整示例

4. 功能介绍

4.1 方法及其标志

一个字段对应一个验证规则集，一个规则集由多个验证 规则，方法（函数） 和 错误消息模板(可选的) 组成。 为了便于理解以及简化规则，允许采用一些方法 标志 代表实际的方法（函数）。

例如:

完整的方法及其标志见 附录 1 - 方法标志及其含义

4.2 正则表达式

一般以 / 开头，以 / 结尾，表示是正则表达式 正则表达式最后面的 / 之后可能跟随着 模式修饰符，如 /i

支持在一个串联规则中，同时使用多个正则表达式

4.3 方法传参

在以字符串书写的规则中，如何给方法传参呢？

传参的几种方式

1. 标准参数 跟 PHP 函数使用参数一样，参数写在小括号()里面，多个参数以逗号,分隔，,前后不允许多余的空格 例如，

表示 age 必须等于20。这里的 @this 代表当前 age 字段的值。

2. 省略 @this 参数 当参数写在中括号[]里面时，首个 @this 参数可省略不写。 例如，上述例子可简写为：

3. 省略参数 当函数参数只有一个且为当前字段值时，可省略 () 和 [] ，只写方法。 例如，

4. 默认参数 支持默认参数，但需要额外配置。见 设置方法标志 例如，以下表示数据为索引数组，unique 验证其子数据必须是唯一的。但参数每次都得写 @parent 稍显多余，通过配置默认参数，可以省略之。

参数变量表

参数分隔符：

• symbol_parameter_separator: , 将参数字符串分割为多个参数的符号。 例如：equal(@this,1) 以下特殊的情况，, 不会被视为参数分隔符：
  • \,
  • 被 [] 包裹起来的。例如：my_method[[1,2,3],100] 表示这里有两个参数，数组 [1,2,3] 和 整形 100
  • 被 {} 包裹起来的。
• 自定义参数分隔符，见 4.10 客制化配置

参数类型

自动探测参数的类型并强制转换为对应类型。

1. 被双引号（"）或单引号（'）包含的内容即被视为字符串。否则将探测并强制转换类型。
   • 例如 "abc", 'abc' 或者 abc 都被视为字符串 abc
2. 支持转换的类型有：
   • int：例如 123 为整形，"123" 为字符串
   • float: 例如 123.0
   • bool: 例如 false 或者 TRUE
   • array: 例如 [1,2,3] 或者 ["a", "b"]
   • object: 例如 {"a": "A", "b": "B"}
   • 例如： my_method[[1,"2",'3'],100,false,"true"]
   • [1,"2",'3'] 将被转换为 array([1,"2","3"])
   • 100 将被转换为 int(100)
   • false 将被转换为 bool(false)
   • "true" 将被转换为 string(true)

4.4 自定义方法

Validation 类中内置了一些验证方法，例如 *，>, length>=, ip 等等。详见 附录 1 - 方法标志及其含义

如果验证规则比较复杂，内置方法无法满足你的需求，可以拓展你自己的方法。 如果方法中根据不同的判断可能返回不同的错误信息，见 4.13 错误信息模板 - 3. 在方法中直接返回模板 一节。

自定义方法的几种方式

拓展方法有以下几种方式：

1. 新增方法：add_method($method, $callable, $method_symbol = '')

新增一个新的方法

• $method：方法名
• $callable：方法定义
• $method_symbol：方法标志。可选的。

2. 新增方法类：add_rule_class

一个方法类包含多个方法及其标志。支持静态或非静态的方法。 由于优先级原因，如需覆盖验证类 Validation 中的原生方法，请使用新增方法类，拓展类可能无法覆盖。

3. 拓展 Validation 类

拓展 Validation 类并重写内置方法或者增加新的内置方法。推荐用 trait

4. 全局函数

包括系统自带的函数和用户自定义的全局函数。

几种方法的优先级 新增方法 > 新增方法类 > 拓展 Validation 类 > 内置方法 > 全局函数

若方法都不存在，则报错：未定义

设置方法标志

允许设置方法的标志，更加直观。例如，greater_than 的标志是 >。参考 附录 1 - 方法标志及其含义 从上一节中，你应该已经注意到方法标志的使用了。那也是最通用的设置标志的方式。例如，

方法标志 $method_symbols 可能还支持其他属性：

• 如果值为字符串，例如 'cus_str'，则表示标志。
• 如果值为数组，则支持以下字段:
  • symbols: 表示标志，例如 'cus_str'。
  • is_variable_length_argument: 默认为 false。表示方法第二个参数为可变长度参数，规则集 中的第一个参数之后的所有参数都会被第二个参数的子元素。参考 githusband\Rule\RuleClassDefault::$method_symbols['in_number_array']。
  • default_arguments: 默认为 无。设置方法的默认参数。参考 githusband\Rule\RuleClassArray::$method_symbols['is_unique']。
  • default_arguments 数组的键必须是整形数字，表示第几个默认参数. 例如，2 表示第二个参数。
  • default_arguments 数组的值可以是任意值。对于类似 "@parent" (表示当前字段的父数据)，参考 4.3 方法传参

对于 2. 新增方法类，如果支持方法标志的全部属性，例子如下，

4.5 串联并联规则

• 串联：一个参数的多个方法必须全部满足，标志是 |

• 并联：一个参数的多个规则满足其一即可。 两种方法：
  • A. {字段名} + [or]
  • B. 在当前字段下增加唯一子字段 [or]

[or] 的标志是 [||] , 标志支持自定义，使用方法同 [or]

4.6 条件规则

When 条件规则

When 条件规则：给任意规则或方法增设条件，一般只有当条件满足时，才验证该方法，否则跳过该方法。

• 用法：{任意规则或方法} + : + when()
• 规则或方法包括： required, optional, optional_unset, 正则表达式 和 任意方法（比如方法 >=）
• 两种条件规则：when() 和 when_not()，条件写在小括号中间，目前仅支持一个条件。
• 条件规则支持自定义，见 4.10 客制化配置

1. 一般地，只有当条件满足时，才验证该方法，否则跳过该方法。例如：

2. 特殊地，required, optional, optional_unset，这三个规则，可能需要验证字段是否非空。

下面，我以 required 为例，说明 when() 和 when_not() 的用法。

• 2.1 正条件的必要规则：required:when()

1. 如果条件成立，则验证 required 方法
2. 如果条件不成立，说明该字段是可选的： 2.1. 若该字段为空，立刻返回验证成功； 2.2. 若该字段不为空，则继续验证后续方法

• 2.2 否条件的必要规则：required:when_not()

1. 如果条件不成立，则验证 required 方法
2. 如果条件成立，说明该字段是可选的： 2.1. 若该字段为空，立刻返回验证成功； 2.2. 若该字段不为空，则继续验证后续方法

IF 条件规则

IF 条件规则的写法跟 PHP 的 if 结构 语法差不多, 例如：

• if ( expr ) { statement }
• if ( !expr ) { statement }
• if ( expr1 || !expr2 ) { statement1 } else { statement2 }

支持的逻辑操作符：

• !：逻辑操作符否。
  • 条件中不包含 !: 表示当条件结果与布尔值 true 严格相同(===)，则条件成立。
  • 条件中包含 !: 表示当条件结果与布尔值 true 不严格相同(!==)，则条件成立。
• ||：逻辑操作符或。表示其中一个条件成立即可。

执行逻辑是：

1. 如果条件成立，则继续验证后续方法。
2. 如果条件不成立，则不继续验证后续方法，立即返回成功。

例子 1：

例子 2：

例子 3：

对于例子 3 ，需要说明的是，我们只支持一个逻辑否 !, !!=(@id,50) 其实是两个部分，逻辑否 ! 和 方法 not_equal 的标志 !=。标志见 附录 1 - 方法标志及其含义

4.7 无限嵌套的数据结构

支持无限嵌套的数据结构，包括关联数组，索引数组

1. 无限嵌套的关联数组 验证数据怎么写，规则数组就怎么写。例如：

2. 无限嵌套的索引数组 索引数组字段的名称后面加上标志 .*，或者给索引数组字段加上唯一子元素 *

数组自身的规则

上述的例子，一个规则数组便可完成对复杂结构的数据的验证。但只能对叶子字段进行验证，如果要对父数组本身进行验证，还无法实现。 那么，我们设计通过一个 __self__ 叶子字段，表示父数组本身的规则。

• __self__ 字段允许自定义，见 4.10 客制化配置
• 特殊的，如果数组本身规则只有可选的 optional，有简便的写法，见 4.8 可选字段

1. 关联数组的自身规则

2. 索引数组的自身规则

4.8 可选字段

1. 一般的，对于一个叶子字段（无任何子字段），可以直接使用 optional 方法，表示该字段是可选的。
2. 有时候，数组也是可选的，但是一旦设置，其中的子元素必须按规则验证。对于这种情况，只需要在数组字段名后面加上 [optional]，表示该数组是可选的。
3. 与在字段名后面加上 [optional] 一样的效果，给字段增加唯一子元素 [optional]，也表示该字段是可选的。
4. [optional] 的标志是 [O]，两者可以互相替换。

例如：

4.9 特殊的验证规则

特殊规则列表：

注意：标志使用方法和全称一样，且标志支持 客制化。

4.10 客制化配置

支持客制化的配置有：

例如，你觉得我设计的规则太丑了，一点都不好理解。😡 于是你做了如下的定制:

那么，1.2 一个例子 中的规则可以这么写：

是不是变得更加漂亮了呢？😍 快来试试吧！

启用实体（重点）

如你所见，规则集都是用字符串书写的，每次验证数据，我们需要将规则集解析成一个个规则，再将规则解析成方法及其参数，最后验证对应数据。 对于 php-fpm 的请求，每一个请求都将启动一个进程，一般只需验证一个数据，结束请求后进程也销毁，所以开启实体反而浪费性能。 但对于常驻后台的服务, 例如 swoole，可以开启实体配置，将规则集解析成实体类，避免重复解析的问题。

• enable_entity: 默认 false。

启用实体不会影响验证数据过程产生任何变化。如果你对实体结构感兴趣，请看这里。

4.11 国际化

为不同的方法定制默认的错误消息模板。见 4.13 错误信息模板 - 第 3 点

国际化列表

• 国际化文件名和类名都采用大驼峰命名方式。
• 通过 4.10 客制化配置 修改默认错误信息模板。
• 通过 set_language 方法修改默认错误信息模板。支持用类名或者别名作为参数。

创建你的国际化文件

1. 创建文件 /MyPath/MyLang.php

如果方法有对应的标志，比如 equal 的标志是 =, 那么这里的键推荐用方法标志 =。 如果方法没有对应标志，那么就只能用方法名，比如 check_custom

2. 配置国际化文件的路径

直接使用国际化对象 实际上，上面国际化文件的方法最终调用的是 custom_language 接口。

4.12 验证全部数据

默认地，即使某个字段验证失败，也会继续验证后续的全部数据。 可设置当任意字段验证失败后，立即结束验证后续字段。

4.13 错误信息模板

如何判定方法验证失败？ 当且仅当方法 返回值 === true 时，表示验证成功，否则表示验证失败。

当一个字段验证失败，你可能希望

• 为整个规则集设置一个错误信息模板
• 为规则集中的每一个规则单独设置一个错误信息模板

那么，你有多个途径可以设置错误信息模板：

1. 在规则集中设置一个统一的模板(普通字符串)
2. 在方法中直接返回模板(普通字符串)
3. 为每一个方法定制模板 3.1. 在 规则集 中设置临时模板(JSON字符串等) 3.2. 通过 国际化 设置默认的模板

模板优先级 从高到低：1 > 2 > 3

支持被单独设置模板的方法，要求：

• 方法返回 false: 根据方法或标志匹配错误信息模板
• 方法返回标志：根据返回的标志匹配错误信息模板 比如 TAG:=，根据 = 匹配错误信息模板

模板变量

1. 在 规则集 中设置临时模板

临时模板只对当前规则集有效，对其他规则集无效。

1.1 在一个规则集的最后，加入标志 ">>", 注意前后各有一个空格。自定义标志见 4.10 客制化配置

1.1.1. 普通字符串：表示无论规则中的任何方法验证失败，都使用此错误信息 它对当前字段的所有规则都生效。无论方法返回 false 或者其他错误模板，都使用此错误信息

1.1.2. JSON 字符串：为每一个方法设置一个错误信息模板 它只对对应的规则都生效。如果方法返回 false，则使用对应的错误信息

当其中任一方法验证错误并返回 false，对应的报错信息为

• required: Users define - id is required
• /^\d+$/: Users define - id should be "MATCHED" /^\d+$/
• >=<=: id must be greater than or equal to 1 and less than or equal to 100

1.1.3. 专属字符串（不推荐）：为每一个方法设置一个错误信息模板，同 JSON

1.2. 错误信息模板数组：为每一个方法设置一个错误信息模板，同 JSON

• 键 0: 验证规则
• 键 error_message：错误信息模板数组

不允许包含任何其他键。

2. 在方法中直接返回模板

当且仅当方法 返回值 === true 时，表示验证成功，否则表示验证失败。

所以方法允许四种错误返回：

• 返回 false (支持国际化) 根据方法的标志匹配错误信息模板，见 附录 1 - 方法标志及其含义

• 返回标志 (支持国际化) 根据返回的标志匹配错误信息模板。比如标志 is_exclude_animal

• 返回错误信息模板

• 返回错误信息模板数组，默认有两个字段，error_type 和 message，可自行增加其他字段

3. 通过国际化设置默认模板

默认模板对所有规则集生效，但可能被临时模板替代。

见 4.11 国际化

4.14 错误信息格式

一共有四种不同的错误信息格式：

• ERROR_FORMAT_NESTED_GENERAL: 'NESTED_GENERAL'

• ERROR_FORMAT_NESTED_DETAILED: 'NESTED_DETAILED' 这种格式和上面的格式类似，只是错误信息变成了数组，包含更多的错误信息。

• ERROR_FORMAT_DOTTED_GENERAL: 'DOTTED_GENERAL'

• ERROR_FORMAT_DOTTED_DETAILED: 'DOTTED_DETAILED' 这种格式和上面的格式类似，只是错误信息变成了数组，包含更多的错误信息。

详见 附录 3 - 错误信息格式

附录 1 - 方法标志及其含义

• is_variable_length_argument: 表示方法第二个参数是否为可变长度参数。即方法第二个参数为数组，规则集中第一个参数之后的所有参数，都被视为方法的第二个参数的子元素。

如果您不知道如何使用附录中的任意方法，请于 tests 文件夹中搜索 test_method_ + 方法名。例如：

• test_method_is_uuid
• test_method_datetime_between

里面有详细的示例。

目前暂无方法的使用文档。

附录 2 - 验证完整示例

设想一下，如果用户数据如下，它包含关联数组，索引数组，我们要如何定制规则去验证它，如何做到简单直观呢？

附录 3 - 错误信息格式

一维字符型结构

一维关联型结构

无限嵌套字符型结构

无限嵌套关联型结构