当前位置：首页 > news >正文

构建一个简洁优雅的 PHP 参数验证器 —— php-schema-validator

news 2025/8/11 6:32:27

在日常开发中，参数校验是绕不过的一道坎。我们常常需要确保用户传入的数据符合预期格式，比如必填字段、数据类型、最大长度、邮箱格式等等。虽然许多 PHP 框架都内置了验证器，但在开发轻量服务、非框架项目，或需要在业务中后端进行结构化数据校验时，我总觉得现有方案不够灵活、冗余较多。

于是，我动手写了一个开箱即用、易扩展、轻量级的参数验证器：php-schema-validator

为什么要造这个轮子？

虽然 PHP 社区有很多验证类库（如 Laravel 的 Validator、Respect\Validation、Opis JSON Schema 等），但它们往往：

要么依赖框架，不方便独立使用；
要么语法冗长，无法用简洁的规则表达复杂校验；
要么扩展性差，自定义规则成本高。

我想要一个东西，既能用类似 JSON Schema 的方式表达规则，又能非常容易地扩展，同时尽量保持核心代码简洁明了。
于是这个项目诞生了。

核心设计理念

这个库的核心目标可以总结为三句话：

规则驱动 —— 用数组描述你的字段规则，声明式更直观；
可扩展 —— 每一个验证规则都是独立的类，插件化设计；
无依赖 —— 不依赖框架，适用于任意 PHP 项目。

安装方式很简单：

composer require hejunjie/schema-validator

一个简单示例：

use Hejunjie\SchemaValidator\Validator;
use Hejunjie\SchemaValidator\Exceptions\ValidationException;$data = ['name'   => '张三','age'    => 28,'email'  => 'invalid-email',
];// 自定义扩展，返回 true 则规则通过，否则均视为不通过
Validator::extend('is_zh', function ($field, $value, $params = null) {if (preg_match('/^[\x{4e00}-\x{9fa5}]+$/u', $value)) {return true;}
});try {Validator::validate($data, ['name'  => ['is_zh', 'string', 'minLength:2'],'age'   => ['integer', 'between:18,60'],'email' => ['required', 'email'],]);echo "验证通过 ✅";
} catch (ValidationException $e) {echo "验证失败 ❌" . PHP_EOL;print_r($e->getErrors());  // 友好打印错误信息
}

输出类似：

验证失败 ❌
Array
([email] => Array([0] => email))

支持的验证规则

目前内置了这些基础规则（并持续扩展中）：

类型类：支持 string / integer / boolean / array / object / float / numeric
比较类：支持 min / max / between / length / min_length / max_length / gt / lt / gte / lte
格式类：支持 email / mobile / url / ip / json / alpha / alpha_num / alpha_dash
布尔类：支持 required / accepted / declined
自定义类：支持 starts_with / ends_with / contains

如何扩展一个自定义规则？

比如我想加一个 is_zh（只允许输入中文）规则：

use Hejunjie\SchemaValidator\Validator;// 在调用 Validator::validate 之前
Validator::extend('is_zh', function ($field, $value, $params = null) {if (preg_match('/^[\x{4e00}-\x{9fa5}]+$/u', $value)) {return true;}
});

然后就可以直接使用：

use Hejunjie\SchemaValidator\Validator;
use Hejunjie\SchemaValidator\Exceptions\ValidationException;try {Validator::validate($data, ['name'  => ['is_zh'],]);// 验证成功
} catch (ValidationException $e) {// 验证失败
}