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

用于對API接口的請求參數(shù)進(jìn)行合法性檢查。

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

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

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

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

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

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

目錄

1 簡介

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

1.2 特點

1.3 一個簡單示例

2 安裝

3 快速上手

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

3.2 驗證不通過的錯誤處理

3.3 在第三方框架中的用法

4 詳細(xì)使用方法

4.1 驗證整型參數(shù)

4.2 驗證浮點型參數(shù)

4.3 驗證bool型參數(shù)

4.4 驗證字符串型參數(shù)

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

4.6 驗證器串聯(lián)（與）

4.7 Required 驗證器

4.8 忽略所有 Required 驗證器

4.9 嵌套參數(shù)的驗證

4.10 條件判斷型驗證器

4.11 驗證規(guī)則并聯(lián)（或）

4.12 關(guān)于特殊值null, ""，0，false的問題

4.13 關(guān)于基本數(shù)據(jù)類型與字符串的關(guān)系

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

4.15 國際化

4.16 國際化（0.4版之前）

A 附錄 - 驗證器列表

A.1 整型

A.2 浮點型

A.3 bool型

A.4 字符串型

A.5 數(shù)組型

A.6 對象型

A.7 文件型

A.8 日期和時間型

A.9 條件判斷型

A.10 其它驗證器

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

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

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

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

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

支持無限嵌套的數(shù)據(jù)結(jié)構(gòu)的驗證（參考 1.3 節(jié)的例子）

支持條件驗證，根據(jù)參數(shù)取值不同，應(yīng)用不同的驗證規(guī)則（參考 1.3 節(jié)的例子）

支持正則表達(dá)式驗證

簡潔，驗證邏輯一目了然

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

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

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

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

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

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

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

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

通過Composer安裝

composer require webgeeker/validation:^0.4

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

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

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

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

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

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

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

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

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

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

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

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

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

這條驗證要求參數(shù)"height"是浮點數(shù)，并且大于等于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"開頭。只接收字符串型數(shù)據(jù)，其它數(shù)據(jù)類型均不匹配。

例1：

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

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

例2：

"comment" => "ByteLenLe:1048576"

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

例3：

"email" => "Email"

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

例4（正則表達(dá)式驗證）：

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

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

關(guān)于正則表達(dá)式中的哪些特殊字符需要轉(zhuǎn)義的問題，只需要用 preg_match() 函數(shù)驗證好，如：

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

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

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

參考附錄A.5-A.8

一條規(guī)則中可以有多個驗證器前后串聯(lián)，它們之間是“AND”的關(guān)系，如：

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

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

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

如果多個驗證器串聯(lián)，Required驗證器必須在其它驗證器前面。

如果還有條件驗證器，Required必須串聯(lián)在條件驗證器后面。

如果驗證規(guī)則中沒有 Required，當(dāng)參數(shù)存在時才進(jìn)行驗證，驗證不通過會拋異常；如果參數(shù)不存在，那么就不驗證（相當(dāng)于驗證通過）

例：

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

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

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

$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); // 創(chuàng)建用戶時的驗證

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

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

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

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

$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",
    ],
];

參數(shù)"sex"的值不同，參數(shù)"height"的驗證規(guī)則也不一樣。

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

多條驗證規(guī)則可以并聯(lián)，它們之間是“或”的關(guān)系，如

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

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

驗證規(guī)則并聯(lián)不是簡單的“或”的關(guān)系，具體驗證流程如下：

按順序驗證這些規(guī)則，如果有一條驗證規(guī)則通過, 則該參數(shù)驗證通過。

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

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

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

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

""是字符串。

0是整型。

false是bool型。

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

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

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

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

與

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

是等價的。

對于以下url地址

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

我們將得到的參數(shù)數(shù)組：

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

注意：

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

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

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

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

因為常規(guī)的HTTP請求，所有的基本數(shù)據(jù)類型最終都會轉(zhuǎn)換成字符串，所以：

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

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

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

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

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

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

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

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

看下面的例子：

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

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

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

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

參考附錄A.10獲取更詳細(xì)的信息

從0.4版開始：

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

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

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

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

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

下面提供一個示例類：

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