Filter - APIPHP开源框架

>i 本文档的最新修订日期是： > **2023-10-23** # Filter ## 模块简述对数据进行校验。 ## 模块配置配置文件位于 `/config/core/Filter.php` 。 * **`rule`** `(Array)` `~` ：用以指定验证规则。值为一个一维数组，数组中元素的 `键` 为规则的名称（不可包含分隔符 `|`），元素的`值` 为正则表达式字符串。本模块已内置了如下规则名称，如果重复定义将不会生效： * `email` 用以验证数据是否为合法的电邮地址。 * `ip` 用以验证数据是否为合法的IPv4或IPv6地址。 * `url` 用以验证数据是否为合法的URL。 * `json` 用以验证数据是否为合法的JSON字符串。 ## :: byMode()方法 ### 语法 **Filter :: byMode ( <kbd>传参数组</kbd> )** ### 说明对来自GET/POST/HEADER的数据的进行校验。此方法 `支持` 中文参数名。 ### 参数 * **`field（字段）`** `(Array)` `必须`：指定字段和校验规则。此参数为一个一维数组，数组的键为 `字段名` ，值为 `非空检查[,最小长度] [,最大长度] [,校验规则]` 的字符串。其中，`字段名` 为需要检查的字段名称，`非空检查` 为检查字段对应的值是否为空（值为 `TRUE` 或 `FALSE` ），`最小长度` 为字段允许的值的最小长度，`最大长度` 为字段允许的值的最大长度（ `0` 为不限制），`校验规则` 为模块配置项 `rule` 中所定义的校验规则，或一个可选值的列表。如果希望待校验的数据必须为某几个值中的一个，则需要将多个值通过分隔符 `|` 分开并作为 `校验规则` 传入，例如： ```PHP $Config = [ '字段' => [ 'delete' => 'TRUE,0,0,true|false', 'mode' => 'TRUE,0,0,default|default' //指定值必须为default ], '模式' => 'POST' ]; \core\Filter::byMode($Config); ``` 模块配置项 `rule` 中已经预先提供了常用的中国大陆电话号码、身份证号码等格式的校验规则，详情见本模块配置文件中此配置项内的注释说明。 * **`optional（可选）`** `(Array)` `[]`：用以指定可选（非必须）的字段。此参数为一个一维数组，数组的键无需定义，值为 `字段名` 的字符串。若某个字段在本参数数组元素内，则仅当该字段存在时才进行校验。 * **`mode（模式）`** `(String)` `必须`：用以指定数据的来源。此参数的必须是 `GET/POST/HEADER` 中的一个。 ### 返回 `(Bool)` 类型。 `TRUE` 代表校验通过、`FALSE` 代表校验未通过。 ### Hook * **`apiphp_filter_mode-verify-failed`** `/lib/core/Filter.php` `无需返回` ：当校验未通过时，在返回 `false` 之前，于 `Filter::byMode()` 中被调用。传参数组中 `field` 元素的值即为未通过校验的字段值。传参数组中 `result` 元素为一个一维数组，代表字段的校验结果明细，子元素的键为 `字段名`，子元素的值为 `true` 时即为通过校验，值为 `false` 时则为未通过校验。各子元素的含义如下： * `0` ：非空校验。 * `1` ：长度校验。 * `2` ：规则校验。 ## :: lastCheck()方法 ### 语法 **Filter :: lastCheck ( <kbd>传参数组</kbd> )** ### 说明返回最后一次使用 `byMode()` 方法校验数据的校验结果。 ### 参数无。 ### 返回 `(Array)` 类型。数组中 `result` 元素为一个一维数组，代表字段的校验结果明细，子元素的键为 `字段名`，当子元素的值为 `true` 时即为通过校验，值为 `false` 时则为未通过校验。各子元素的含义如下： * `0` ：非空校验。 * `1` ：长度校验。 * `2` ：规则校验。数组中 `optional` 元素为一个一维数组，代表可选的字段是否存在，子元素的键为 `字段名`，当子元素的值为 `true` 时存在该字段，值为 `false` 时则为不存在该字段。 >i 由于 `byMode()` 遇到检验不通过的数据时会立即终止校验流程并返回 `byMode()`，因此本方法返回的数组中不一定包含完整的参数列表。 ## :: byData()方法 ### 语法 **Filter :: byData ( <kbd>传参数组</kbd> )** ### 说明对传入数据的进行校验。此方法 `支持` 中文参数名。 ### 参数 * **`data（数据）`** `(String)` `必须`：用以指定需要校验的数据。 * **`check（校验）`** `(String)` `必须`：指定校验规则。此参数的值为 `非空检查[,最小长度] [,最大长度] [,校验规则]` 的字符串。其中，`非空检查` 为检查字段对应的值是否为空（值为 `TRUE` 或 `FALSE` ），`最小长度` 为字段允许的值的最小长度，`最大长度` 为字段允许的值的最大长度，`校验规则` 为模块配置项 `Rule` 中所定义的校验规则。模块配置项 `Rule` 中已经预先提供了常用的中国大陆电话号码、身份证号码等格式的校验规则，详情见本模块配置文件中此配置项内的注释说明。 ### 返回 `(Bool)` 类型。 `TRUE` 代表校验通过、`FALSE` 代表校验未通过。