在日常開發中，參數校驗是繞不過的一道坎。我們常常需要確保用户傳入的數據符合預期格式，比如必填字段、數據類型、最大長度、郵箱格式等等。雖然許多 PHP 框架都內置了驗證器，但在開發輕量服務、非框架項目，或需要在業務中後端進行結構化數據校驗時，我總覺得現有方案不夠靈活、冗餘較多。

於是，我動手寫了一個開箱即用、易擴展、輕量級的參數驗證器：php-schema-validator

為什麼要造這個輪子？

雖然 PHP 社區有很多驗證類庫（如 Laravel 的 Validator、Respect\Validation、Opis JSON Schema 等），但它們往往：

• 要麼依賴框架，不方便獨立使用；
• 要麼語法冗長，無法用簡潔的規則表達複雜校驗；
• 要麼擴展性差，自定義規則成本高。

我想要一個東西，既能用類似 JSON Schema 的方式表達規則，又能非常容易地擴展，同時儘量保持核心代碼簡潔明瞭。
於是這個項目誕生了。

核心設計理念

這個庫的核心目標可以總結為三句話：

1. 規則驅動 —— 用數組描述你的字段規則，聲明式更直觀；
2. 可擴展 —— 每一個驗證規則都是獨立的類，插件化設計；
3. 無依賴 —— 不依賴框架，適用於任意 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) {
    // 驗證失敗
}

如果有常用自定義規則，建議在代碼中封裝 Validator::validate 方法，在調用 validate 之前通過 extend 方法註冊自定義規則

在常駐內存的項目中，建議在項目運行初始化時全局註冊，以減小性能開銷

項目地址 & 使用方式

GitHub 倉庫地址：
🔗 https://github.com/zxc7563598/php-schema-validator

歡迎 Star、提 Issue、提 PR！

下一步計劃

我還在考慮以下幾點：

• 錯誤信息多語言支持
• Laravel / Webman / Hyperf 插件適配
• 添加更多內置規則（銀行卡號、身份證號、UUID 等）
• 將 schema 校驗支持 YAML / JSON 文件描述

最後

這是一個“造輪子”項目，但也是一個“實踐設計”的項目。如果你也曾因為參數驗證的重複勞動而煩惱，不妨來試試這個輕量、可擴展的驗證器。

如果這個庫對你有幫助，歡迎 Star、提建議或一起共建 🚀