摘要：用于對接口的請求參數進行合法性檢查。唯一不符合這一規則的是字符串型驗證器，它們一部分以開頭的，但也有一部分不以開頭，比如等。驗證型參數型驗證器只有兩個合法的取值為字符串忽略大小寫。合法的取值為字符串忽略大小寫例完整的型驗證器的列表參考附錄。

用于對API接口的請求參數進行合法性檢查。

在實現服務端的API接口時，對于每一個接口的每一個參數，都應該檢測其取值是否合法，以免錯誤的數據輸入到系統中。這個工作可以說是費時費力，但又不得不做。而且PHP本身是弱類型語言，不但要驗證取值，還要驗證數據的類型是否符合，這就更復雜了。

本工具就是針對這個工作而設計的，能夠有效地減少編碼量，代碼可讀性好。

看看下面這段代碼，可以對用法有個大概印象，應該不難看懂：

$params = $request->query(); // 獲取GET參數

// 驗證（如果驗證不通過，會拋出異常）
Validation::validate($params, [
    "offset" => "IntGe:0",
    "count" => "Required|IntGeLe:1,200",
]);

支持多種數據類型的校驗：整型、浮點型、bool型、字符串、數組、對象、文件、日期時間，能夠驗證嵌套的數據結構中的參數，還支持帶條件判斷的驗證。

目錄

1 簡介

1.1 為什么要寫這樣一個工具?

1.2 特點

1.3 一個簡單示例

2 安裝

3 快速上手

3.1 一個完整的示例（不使用任何框架）

3.2 驗證不通過的錯誤處理

3.3 在第三方框架中的用法

4 詳細使用方法

4.1 驗證整型參數

4.2 驗證浮點型參數

4.3 驗證bool型參數

4.4 驗證字符串型參數

4.5 驗證數組型、對象型、文件型、日期時間型參數

4.6 驗證器串聯（與）

4.7 Required 驗證器

4.8 忽略所有 Required 驗證器

4.9 嵌套參數的驗證

4.10 條件判斷型驗證器

4.11 驗證規則并聯（或）

4.12 關于特殊值null, ""，0，false的問題

4.13 關于基本數據類型與字符串的關系

4.14 自定義錯誤信息輸出文本

4.15 國際化

4.16 國際化（0.4版之前）

A 附錄 - 驗證器列表

A.1 整型

A.2 浮點型

A.3 bool型

A.4 字符串型

A.5 數組型

A.6 對象型

A.7 文件型

A.8 日期和時間型

A.9 條件判斷型

A.10 其它驗證器

我在使用Laravel框架的時候，Laravel提供了一個參數驗證工具，不過用起來不怎么順暢：

每一個驗證都寫一個驗證類（繼承XXX），這樣太麻煩，而且系統中會多出許多許多的類；如果這些類在多處被復用，或者為了“更加”復用（減少重復代碼），再在這些類之間搞出很多的繼承關系，那么這些類的維護本身就是一個大問題；

驗證器有“一詞多義”的問題。比如它有一個size驗證器，它同時支持驗證字符串、整型、文件等多種類型的參數，針對不同數據類型size的含義不一樣。這就好比你去背英語單詞，有那么一些英語單詞，它有很多很多意思，不同的語境下有不同的含義。比如"present"這個單詞，它既有“呈現”、“出席”的意思，也有“禮物”的意思。這種一詞多義的單詞最讓人頭疼了，搞不清它到底什么意思，而且記不住啊。

為了解決這些問題，所以才寫了這么一個工具。

每個功能特性都有單元測試（共有 41 tests, 369 assertions）

支持無限嵌套的數據結構的驗證（參考 1.3 節的例子）

支持條件驗證，根據參數取值不同，應用不同的驗證規則（參考 1.3 節的例子）

支持正則表達式驗證

簡潔，驗證邏輯一目了然

輕量，不需要定義和維護各種驗證classes

驗證器語義明確，沒有“一詞多義”的問題

易學易記。比如整型驗證器都是以"Int"開頭，浮點型驗證器都是以"Float"開頭，等等。唯一不符合這一規則的是字符串型驗證器，它們一部分以"Str"開頭的，但也有一部分不以"Str"開頭，比如Regexp, Ip, Email, Url等。

不綁定任何一個框架，無任何依賴。你可以在任何一個框架中使用這個工具，就算你不使用框架，也可以使用本工具。

下面這個示例展示了一個查詢獲取用戶投訴列表的Request參數的驗證（注意其中的條件驗證和針對嵌套數據結構的驗證）：

//驗證規則
$validations = [
    "offset" => "IntGe:0", // 參數offset應該大于等于0
    "count" => "Required|IntGeLe:1,200", // 參數count是必需的且大于等于1小于等于200
    "type" => "IntIn:1,2", // 參數type可取值為: 1, 2
    "state" => [
        "IfIntEq:type,1|IntEq:0", // 如果type==1（批評建議），那么參數state只能是0
        "IfIntEq:type,2|IntIn:0,1,2", // 如果type==2（用戶投訴），那么參數state可取值為: 1, 2, 3
    ],
    "search.keyword" => "StrLenGeLe:1,100", // search.keyword 應該是一個長度在[1, 100]之間的字符串
    "search.start_time" => "Date", // search.start_time 應該是一個包含合法日期的字符串
    "search.end_time" => "Date", // search.end_time 應該是一個包含合法日期的字符串
];

// 待驗證參數
$params = [
    "offset" => 0, // 從第0條記錄開始
    "count" => 10, // 最多返回10條記錄
    "type" => 2, // 1-批評建議, 2-用戶投訴
    "state" => 0, // 0-待處理, 1-處理中, 2-已處理
    "search" => [ // 搜索條件
        "keyword" => "硬件故障", // 關鍵字
        "start_time" => "2018-01-01", // 起始日期
        "end_time" => "2018-01-31", // 結束日期
    ],
];

// 驗證（如果驗證不通過，會拋出異常）
Validation::validate($params, $validations);

通過Composer安裝

composer require webgeeker/validation:^0.4

這個例子直接驗證$_POST（POST表單）中的參數，展示了最基本的用法

 "IntGe:0", // 參數offset應該大于等于0
        "count" => "Required|IntGeLe:1,200", // 參數count是必需的且大于等于1小于等于200
    ]);
} catch (Exception $e) {
    echo $e->getMessage();
}

注意：驗證不通過會拋出異常，該異常中包含有錯誤描述信息

如果驗證不通過，Validation::validate(...)方法會拋出異常，建議在框架層面統一捕獲這些異常，提取錯誤描述信息并返回給客戶端。

第三方框架一般會提供Request對象，可以取到GET, POST參數（以Laravel為例）

//$params = $request->query(); // 獲取GET參數
$params = $request->request->all(); // 獲取POST參數

// 驗證（如果驗證不通過，會拋出異常）
Validation::validate($params, [
    // 此處省略驗證規則
]);

整型驗證器全部以"Int"開頭，用于驗證整型數值（如123）或整型字符串（如"123"）。其它數據類型均不匹配。

"size" => "IntGeLe:1,100"

這條驗證要求參數"size"是整數，并且大于等于1，小于等于100。

完整的整型驗證器的列表參考附錄 A.1 。

浮點型驗證器全部以"Float"開頭，用于驗證浮點型數值（如1.0）、浮點型字符串（如"1.0"）、整型數值（如123）或整型字符串（如"123"）。其它數據類型均不匹配。

"height" => "FloatGeLe:0.0,100.0"

這條驗證要求參數"height"是浮點數，并且大于等于0，小于等于100.0。

完整的浮點型驗證器的列表參考附錄 A.2 。

bool型驗證器只有兩個：

Bool: 合法的取值為: true, false, "true", "false"（字符串忽略大小寫）。

BoolSmart: 合法的取值為: true, false, "true", "false", 1, 0, "1", "0", "yes", "no", "y", "n"（字符串忽略大小寫）

例

"accept" => "BoolSmart"

完整的bool型驗證器的列表參考附錄 A.3 。

字符串型驗證器不全以"Str"開頭。只接收字符串型數據，其它數據類型均不匹配。

例1：

"name" => "StrLenGeLe:2,20"

這條驗證要求參數"name"是字符串，長度在2-20之間（字符串長度是用mb_strlen()來計算的）。

例2：

"comment" => "ByteLenLe:1048576"

這條驗證要求參數"comment"是字符串，字節長度不超過1048576（字節長度是用strlen()來計算的）。

例3：

"email" => "Email"

這條驗證要求參數"email"是必須是合法的電子郵件地址。

例4（正則表達式驗證）：

"phone" => "Regexp:/^1(3[0-9]|4[579]|5[0-35-9]|7[0135678]|8[0-9]|66|9[89])d{8}$/"

這條驗證要求參數"phone"是合法的手機號。

關于正則表達式中的哪些特殊字符需要轉義的問題，只需要用 preg_match() 函數驗證好，如：

preg_match("/^string$/", $string);

然后把兩個"/"號及其中間的部分拷貝出來，放在Regexp:后面即可，不需要再做額外的轉義，即使正則中有"|"這種特殊符號，也不需要再轉義。

完整的字符串型驗證器的列表參考附錄 A.4 。

參考附錄A.5-A.8

一條規則中可以有多個驗證器前后串聯，它們之間是“AND”的關系，如：

"file" => "FileMaxSize:10m|FileImage"

這個驗證要求參數"file"是一個圖像文件，并且文件大小不超過10m

Required驗證器要求參數必須存在，且其值不能為null（這個是PHP的null值，而不是字符串"null"）（參數值為null等價于參數不存在）。

如果多個驗證器串聯，Required驗證器必須在其它驗證器前面。

如果還有條件驗證器，Required必須串聯在條件驗證器后面。

如果驗證規則中沒有 Required，當參數存在時才進行驗證，驗證不通過會拋異常；如果參數不存在，那么就不驗證（相當于驗證通過）

例：

"size" => "Required|StrIn:small,middle,large"

該驗證要求參數"size"必須是字符串的"small", "middle"或者"large"。

比如當創建一個用戶時，要求姓名、性別、年齡全部都要提供；但是當更新用戶信息時，不需要提供全部信息，提供哪個信息就更新哪個信息。

$validations = [
    "name" => "Required|StrLenGeLe:2,20",
    "sex" => "Required|IntIn:0,1",
    "age" => "Required|IntGeLe:1,200",
];

$userInfo = [
    "name" => "tom",
    "sex" => "0",
    "age" => "10",
];
Validation::validate($userInfo, $validations); // 創建用戶時的驗證

unset($userInfo["age"]); // 刪除age字段
Validation::validate($userInfo, $validations, true); // 更新用戶信息時的驗證

注意上面代碼的最后一行：validate()函數的第三個參數為true表示忽略所有的 Required 驗證器。

這樣我們就只需要寫一份驗證規則，就可以同時用于創建用戶和更新用戶信息這兩個接口。

下面這個例子展示了包含數組和對象的嵌套的參數的驗證：

$params = [
    "comments" => [
        [
            "title" => "title 1",
            "content" => "content 1",
        ],
        [
            "title" => "title 1",
            "content" => "content 1",
        ],
        [
            "title" => "title 1",
            "content" => "content 1",
        ],
    ]
];

$validations = [
    "comments[*].title" => "Required|StrLenGeLe:2,50",
    "comments[*].content" => "Required|StrLenGeLe:2,500",
];

Validation::validate($params, $validations);

條件判斷型驗證器都以"If"開頭。

比如你想招聘一批模特，男的要求180以上，女的要求170以上，驗證可以這樣寫：

$validations = [
    "sex" => "StrIn:male,female",
    "height" => [
        "IfStrEq:sex,male|IntGe:180",
        "IfStrEq:sex,female|IntGe:170",
    ],
];

參數"sex"的值不同，參數"height"的驗證規則也不一樣。

完整的條件判斷型驗證器的列表參考附錄 A.9 。

多條驗證規則可以并聯，它們之間是“或”的關系，如

"type" => [
    "StrIn:small,middle,large",
    "IntIn:1,2,3",
]

上面這條驗證要求參數"type"既可以是字符串"small", "middle"或"large"，也可以整型的1, 2或3

驗證規則并聯不是簡單的“或”的關系，具體驗證流程如下：

按順序驗證這些規則，如果有一條驗證規則通過, 則該參數驗證通過。

如果全部驗證規則都被忽略（If驗證器條件不滿足，或者沒有Required驗證器并且該參數不存在，或者有0條驗證規則），也算參數驗證通過。

上面兩條都不滿足, 則該參數驗證失敗。

這些規則如果要完全理清并不是一件容易的事，所以不建議使用驗證規則并聯，也盡量不要設計需要這種驗證方式的參數。

這些特殊的值是不等價的，它們是不同的數據類型（需要用不同的驗證器去驗證）：

""是字符串。

0是整型。

false是bool型。

null是PHP的空。在本工具中它有特殊的含義。

如果某個參數的值為null，則本工具會視為該參數不存在。

比如下面兩個array對于本工具來說是等價的.

$params = [
    "name" => "hello",
];

與

$params = [
    "name" => "hello",
    "comment" => null,
];

是等價的。

對于以下url地址

http://abc.com/index.php?p1=&&p2=hello&&p3=123

我們將得到的參數數組：

$params = [
    "p1" => "",
    "p2" => "hello",
    "p3" => "123",
];

注意：

參數"p1"的值為空字符串""，而不是null。

參數"p3"的值為字符串"123"，而不是整型123。

GET方式的HTTP請求是傳遞不了null值的。

本工具的所有驗證器都是強類型的，"Int"驗證的是整型，"Float"驗證的是浮點型，"Str*"驗證的是字符串型，數據類型不匹配，驗證是通不過的。但是字符串類型是個例外。

因為常規的HTTP請求，所有的基本數據類型最終都會轉換成字符串，所以：

整型123和字符串"123"均可以通過驗證器"Int"的驗證；

浮點型123.0和字符串"123.0"均可以通過驗證器"Float"的驗證；

bool型true和字符串"true"均可以通過驗證器"Bool"的驗證；

但是null值和字符串"null"永遠不等價，字符串"null"就只是普通的字符串。

如果參數驗證不通過，Validation::validate()方法會拋出異常，這個異常會包含驗證不通過的錯誤信息描述的文本。

但是這個描述文本對用戶來說可能不那么友好，我們可以通過兩個偽驗證器來自定義這些文本：

Alias 用于自定義參數名稱（這個名稱會與內部的錯誤信息模版相結合，生成最終的錯誤信息描述文本）

>>> 用于自定義錯誤描述文本（這個文本會完全取代模版生成的錯誤描述文本）。

看下面的例子：

$params = [
    "title" => "a",
];

Validation::validate($params, [
    "title" => "Required|StrLenGeLe:2,50",
]); // 拋出異常的錯誤描述為：“title”長度必須在 2 - 50 之間

Validation::validate($params, [
    "title" => "Required|StrLenGeLe:2,50|Alias:標題", // 自定義參數名稱
]); // 拋出異常的錯誤描述為：“標題”長度必須在 2 - 50 之間

Validation::validate($params, [
    "title" => "Required|StrLenGeLe:2,50|>>>:標題長度應在2~50之間", // 自定義錯誤信息描述文本
]); // 拋出異常的錯誤描述為：標題長度應在2~50之間

參考附錄A.10獲取更詳細的信息

從0.4版開始：

使用新的靜態成員變量 $langCode2ErrorTemplates 來進行“錯誤提示信息模版”的翻譯，主要目的是簡化格式（感謝 @gitHusband 的建議）。

舊的翻譯表 $langCodeToErrorTemplates 仍然有效，已有代碼無需修改（參考下一節）。如果新舊翻譯表同時提供，優先新的，新表中查不到再使用舊的。

要支持國際化，需要自定義一個類，繼承WebGeekerValidationValidation，重載兩個靜態成員變量：

$langCode2ErrorTemplates用于提供“錯誤提示信息模版”的翻譯對照表。完整的錯誤提示信息模版列表可以在WebGeekerValidationValidation::$errorTemplates成員變量中找到

$langCodeToTranslations用于提供“自定義參數名稱”（由Alias指定）和“自定義錯誤描述文本”（由>>>指定）的翻譯對照表。

下面提供一個示例類：

class MyValidation extends Validation
{
    // “錯誤提示信息模版”翻譯對照表
    protected static $langCodeToErrorTemplates = [
        "zh-tw" => [
            "Int" => "“{{param}}”必須是整數", //