您的位置: 首页> PHP源码

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

匿名上传

发布时间:2025-09-06 11:30:01

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

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

为什么要造这个轮子？

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

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

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

核心设计理念

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

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

安装方式很简单：

composer require hejunjie/schema-validator

一个简单示例：

use HejunjieSchemaValidatorValidator;
use HejunjieSchemaValidatorExceptionsValidationException;

$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 HejunjieSchemaValidatorValidator;

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

然后就可以直接使用：

use HejunjieSchemaValidatorValidator;
use HejunjieSchemaValidatorExceptionsValidationException;

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