Download the PHP package jeckleee/tools without Composer

Jeckleee/Tools

一个 PHP 数据验证和工具库，提供符合直觉的链式调用验证器，让数据验证变得简单高效。

主要特性

• 数据验证 : 提供符合直觉的验证器，使用链式调用添加规则，方便记忆和使用
• 常用工具函数 : 封装了一些常用的数据处理方法
• 支持多种验证方式 : 批量验证、单字段验证、变量验证
• 灵活的配置 : 支持自定义异常、错误码、错误返回模式
• 丰富的验证规则 : 覆盖大部分常用验证场景
• 框架兼容 : 可在 Laravel、Webman、ThinkPHP 等主流 PHP 框架中直接使用

安装

配置

验证规则总览

规则行为详解与注意事项

• required($def = null)
  • 字段必填。若传递 $def，当字段不存在时会自动赋值为 $def 并通过校验。
• ifExisted()
  • 字段存在时才验证，否则跳过。适合可选字段。
• isInt()
  • 接受 int 类型或整数字符串（如 "123"、"-456" 也通过）。
• isNumber()
  • 接受 int、float 及字符串数字（如 "123"、"12.3"）。
• isFloat($decimalPlaces = null)
  • 校验为浮点数，若指定 $decimalPlaces，则小数位数不能超过该值。
• isFile($file, $ext = [], $maxSize_Kb = 500)
  • 支持多种文件对象，校验通过无返回值，失败则抛出异常。
  • $file 可为 $_FILES、Laravel/Webman/ThinkPHP 上传对象。
  • $ext 限制扩展名，空数组不限制。
  • $maxSize_Kb 最大文件大小，单位 KB，默认 500KB。
• isJson(true)
  • 校验为 json 字符串，true 时自动转为数组。
• strAlphaNum(true)
  • 必须同时包含字母和数字。
• requiredWith/requiredWithout
  • 依赖字段存在/不存在时，当前字段必填。
• fun(callable)
  • 传入自定义函数，返回 true 通过，否则抛出异常。

用法示例

1. 批量验证表单数据

2. 验证单个字段

3. 验证变量

4. 自定义验证规则

5. 条件必填验证

6. 字段值比较验证

7. 文件上传验证

8. JSON 字符串校验

9. Base64 编码校验

10. 浮点数校验

11. 数字比较

12. isInt/isNumber/isFloat 区别示例

13. isFile 返回值说明

14. 自定义函数校验

15. 字符串大小写转换

异常处理

自定义异常和错误码

错误返回模式

error_return_mode 只支持 immediate 和 collective，否则会抛出异常。

完整使用示例

工具函数

除了验证器，本工具还提供了一些常用的工具函数：

工具函数说明

• Tool::arrayBindKey($arr, $key)

  • 作用：二维数组按某字段转为以该字段为 key 的关联数组。
  • 示例：

• Tool::arraySequence($arr, $field, $sort = 'SORT_DESC')

  • 作用：按指定字段排序，支持 SORT_ASC/SORT_DESC。
  • 示例：
• Tool::arrayGroupBy($arr, string|callable $key)
  • 作用：按键名或回调分组，返回键为字符串的分组映射。
• Tool::arrayUniqueBy($arr, string|callable $key)
  • 作用：按键稳定去重，保留首次出现的元素。
• Tool::arrayChunkFixed($arr, int $size)
  • 作用：按固定长度分块，size<=0 时返回原数组。
• Tool::arrayPartition($arr, callable $predicate)
  • 作用：按谓词拆分为 [匹配数组, 不匹配数组]。
• Tool::generateTree($list, $idField='id', $parentField='p_id', $children='children')
  • 作用：生成树形结构（基于父子引用）。
• Tool::flattenTree($tree, $children='children')
  • 作用：扁平化树，移除子节点字段。
• Tool::findInTree($tree, callable $predicate, $children='children')
  • 作用：在树中查找首个满足条件的节点。
• Tool::pathInTree($tree, mixed $id, $idField='id', $children='children')
  • 作用：返回从根到目标节点的路径数组，未找到返回空数组。
• Tool::pathInFlat($flat, mixed $id, $idField='id', $parentField='parent_id')
  • 作用：在扁平数组中自底向上追溯父级路径。
• Tool::getRandomString(int $length)
  • 作用：生成长度为 length 的随机字符串（URL 安全字符集）。
• *Tool::maskSecret(string $str, int $startKeep, int $endKeep, string $mask='', ?int $maxLen=null)**
  • 作用：字符串脱敏，支持多字节字符与最大长度限制。
• Tool::humanizeDiff(DateTime|string $datetime)
  • 作用：人性化时间差：刚刚/秒前/分钟前/小时前/天前/日期时间。
• Tool::humanBytes(int|float $bytes, int $precision=2)
  • 作用：人类可读的字节单位展示（B/KB/MB/GB/TB/PB）。
• Tool::buildQuery(array $params)
  • 作用：递归键排序后，按 RFC3986 规则构建查询字符串，稳定可复现。
• Tool::generateUUID()
  • 作用：基于 mt_rand 的不安全 UUID（非加密安全）。
• Tool::uuidV4()
  • 作用：安全 UUID v4（random_bytes），RFC 4122 兼容。
• Tool::uuidV7()
  • 作用：时间有序的 UUID v7，便于索引与排序。
• Tool::randomInt(int $min, int $max)
  • 作用：生成加密安全的随机整数（含边界）。
• Tool::randomFloat(float $min, float $max)
  • 作用：生成 [min, max] 区间随机浮点数。
• Tool::diffDateDays(string $date1, string $date2)
  • 作用：计算两个日期间相差天数。
• Tool::retry(callable $fn, int $times=3, int $sleepMs=100, ?callable $shouldRetry=null)
  • 作用：失败自动重试；可自定义重试判定与重试间隔。

注意事项

1. 验证规则顺序：建议将 required 规则放在最前面，避免对空值进行不必要的验证。
2. 错误消息：可以为每个规则自定义错误消息，提高用户体验。
3. 性能考虑：使用 ifExisted 规则可以避免对不存在字段的验证。
4. 文件验证：文件验证支持多种格式：
   • 原始 $_FILES 数组格式
   • Laravel 的 Illuminate\Http\UploadedFile 对象
   • Webman 的 support\UploadFile 对象
   • ThinkPHP 的 think\file\UploadedFile 对象
5. 条件验证：合理使用 requiredWith 和 requiredWithout 可以处理复杂的表单逻辑。
6. isInt/isNumber 区别：isInt 接受 int 类型 和 字符串整数 ；isNumber 可接受字符串数字 和 浮点数字符串。
7. isFloat：可限制小数位数。
8. isJson：true 时自动转为数组。
9. 框架兼容性：可在 Laravel、Webman、ThinkPHP 等框架中使用。
10. 配置函数依赖：如需自定义配置，需保证 config() 函数可用。

贡献

欢迎提交 Issue 和 Pull Request 来完善这个工具！

许可证

MIT License