主要用於對API請求的引數取值進行合法性驗證。

在實現服務端的API介面時，對於每一個介面的每一個引數，都應該驗證其取值是否合法，以免錯誤的資料輸入到系統中。這個工作可以說是費時費力，但又不得不做。本工具就是針對這個工作而設計的，能夠有效地減少編碼量，程式碼可讀性好。

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

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

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

支援多種資料型別的驗證：整型、浮點型、bool型、字串、陣列、物件、檔案、日期時間，能夠驗證巢狀的資料結構中的引數，還支援帶條件判斷的驗證。

1 簡介

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

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

• 每一個驗證都寫一個驗證類（繼承XXX），這樣太麻煩，而且系統中會多出許多許多的類；如果這些類在多處被複用，或者為了“更加”複用（減少重複程式碼），再在這些類之間搞出很多的繼承關係，那麼這些類的維護本身就是一個大問題；
• 驗證器有“一詞多義”的問題。比如它有一個size
  驗證器，它同時支援驗證字串、整型、檔案等多種型別的引數，針對不同資料型別size的含義不一樣。這就好比你去背英語單詞，有那麼一些英語單詞，它有很多很多意思，不同的語境下有不同的含義。比如"present"這個單詞，它既有“呈現”、“出席”的意思，也有“禮物”的意思。這種一詞多義的單詞最讓人頭疼了，搞不清它到底什麼意思，而且記不住啊。

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

1.2 特點

1. 簡潔，驗證邏輯一目瞭然（參考後面的例子）
2. 輕量，不需要定義和維護各種驗證classes
3. 驗證器語義明確，沒有“一詞多義”的問題
4. 支援正則表示式驗證
5. 支援條件驗證
6. 理論上能夠支援驗證無限巢狀的引數
7. 易學易記。比如整型驗證器都是以"Int"開頭，浮點型驗證器都是以"Float"開頭，等等。唯一不符合這一規則的是字串型驗證器，它們一部分以"Str"開頭的，但也有一部分不以"Str"開頭，比如Regexp
   , Ip, Email, Url等。
8. 不繫結任何一個框架，無任何依賴。你可以在任何一個框架中使用這個工具，就算你不使用框架，也可以使用本工具。

1.3 一個簡單示例

下面這個示例展示了一個查詢獲取使用者投訴列表的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" => "BoolSmart", // 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);

2 安裝

通過Composer安裝

composer require webgeeker/validation:^0.3

3 快速上手

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

這個例子直接驗證$_GET中的引數，展示了最基本的用法

<?php
include "vendor/autoload.php";

use WebGeeker\Validation\Validation;

try {
    Validation::validate($_GET, [
        "offset" => "IntGe:0", // 引數offset應該大於等於0
        "count" => "Required|IntGeLe:1,200", // 引數count是必需的且大於等於1小於等於200
    ]);
} catch (\Exception $e) {
    echo $e->getMessage();
}

注意：驗證不通過會丟擲異常，該異常中包含有錯誤描述資訊

3.2 驗證不通過的錯誤處理

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

3.3 在第三方框架中的用法

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

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

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

4 詳細使用方法

4.1 驗證整型引數

整型驗證器全部以"Int"開頭，用於驗證整型數值（如123）或整型字串（如"123"）。其它資料型別均不匹配。

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

這條驗證要求引數"size"是整數，並且大於等於1，小於等於100。

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

4.2 驗證浮點型引數

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

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

這條驗證要求引數"height"是浮點數，並且大於等於0，小於等於100.0。

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

4.3 驗證bool型引數

bool型驗證器只有兩個：

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

例

"accept" => "BoolSmart"

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

4.4 驗證字串型引數

字串型驗證器不全以"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"是合法的手機號。

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

4.5 驗證陣列型、物件型、檔案型、日期時間型引數

參考附錄A.5-A.8

4.6 驗證器串聯（與）

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

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

這個驗證要求引數"file"是一個影象檔案，並且檔案大小不超過10m

4.7 Required 驗證器

• Required驗證器要求引數必須存在，且其值不能為null（這個是PHP的null值，而不是字串"null"）（引數值為null等價於引數不存在）。
• 如果多個驗證器串聯，Required驗證器必須在其它驗證器前面。
• 如果還有條件驗證器，Required必須串聯在條件驗證器後面。
• 如果驗證規則中沒有 Required，當引數存在時才進行驗證，驗證不通過會拋異常；如果引數不存在，那麼就不驗證（相當於驗證通過）

例：

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

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

4.8 忽略所有 Required 驗證器

比如當建立一個使用者時，要求姓名、性別、年齡全部都要提供；但是當更新使用者資訊時，不需要提供全部資訊，提供哪個資訊就更新哪個資訊。

$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 驗證器。

這樣我們就只需要寫一份驗證規則，就可以同時用於建立使用者和更新使用者資訊這兩個介面。

4.9 巢狀引數的驗證

下面這個例子展示了包含陣列和物件的巢狀的引數的驗證：

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

4.10 條件判斷型驗證器

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

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

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

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

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

4.11 驗證規則並聯（或）

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

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

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

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

1. 按順序驗證這些規則，如果有一條驗證規則通過, 則該引數驗證通過。
2. 如果全部驗證規則都被忽略（If驗證器條件不滿足，或者沒有Required驗證器並且該引數不存在，或者有0條驗證規則），也算引數驗證通過。
3. 上面兩條都不滿足, 則該引數驗證失敗。

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

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

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

• ""是字串。
• 0是整型。
• false是bool型。
• null是PHP的空。在本工具中它有特殊的含義。

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

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

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

與

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

是等價的。

4.13 關於基本資料型別與字串的關係

對於以下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"就只是普通的字串。

4.14 自定義錯誤資訊輸出文字

如果引數驗證不通過，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獲取更詳細的資訊

4.15 國際化

要支援國際化，需要自定義一個類，繼承\WebGeeker\Validation\Validation，過載兩個靜態成員變數：

• $langCodeToErrorTemplates用於提供“錯誤提示資訊模版”的翻譯對照表。完整的錯誤提示資訊模版列表可以在\WebGeeker\Validation\Validation::$errorTemplates成員變數中找到
• $langCodeToTranslations用於提供“自定義引數名稱”（由Alias指定）和“自定義錯誤描述文字”（由>>>指定）的翻譯對照表。

下面提供一個示例類：

class MyValidation extends Validation
{
    // “錯誤提示資訊模版”翻譯對照表
    protected static $langCodeToErrorTemplates = [
        "zh-tw" => [
            "“{{param}}”必須是整數" => "“{{param}}”必須是整數", // ?
            "“{{param}}”必須是字串" => "“{{param}}”必須是字串",
        ],
        "en-us" => [
            "“{{param}}”必須是整數" => "{{param}} must be a integer",
            "“{{param}}”必須是字串" => "{{param}} must be a string",
        ],
    ];

    // 文字翻譯對照表
    protected static $langCodeToTranslations = [
        "zh-tw" => [
            "變數" => "變數", // ?
            "變數必須是整數" => "變數必須是整數", // ⭐
        ],
        "en-us" => [
            "變數" => "variable",
            "變數必須是整數" => "variable must be an integer",
        ],
    ];
}

注意：語言程式碼是區分大小寫的，建議全部用小寫，如"zh-cn", "en-us"等。

使用這個MyValidation類來進行驗證，就可以實現文字的翻譯了。

MyValidation::setLangCode("zh-tw"); // 設定語言程式碼

MyValidation::validate(["var" => 1.0], [
    "var" => "Int", // 既沒有Alias，也沒有>>>，只會翻譯錯誤提示資訊模版
]); // 會丟擲異常：“var”必須是整數

MyValidation::validate(["var" => 1.0], [
    "var" => "Int|Alias:變數", // 有Alias，除了翻譯錯誤提示資訊模版外（對應?那行），還會翻譯引數名稱（對應?那行）
]); // 會丟擲異常：“變數”必須是整數

MyValidation::validate(["var" => 1.0], [
    "var" => "Int|>>>:變數必須是整數", // 有>>>，會翻譯自定義錯誤描述文字（對應⭐那行）
]); // 會丟擲異常：變數必須是整數

如果提供了錯誤的語言程式碼，或者沒有找到翻譯的文字，那麼就不翻譯，輸出原始的文字。

A 附錄 - 驗證器列表

A.1 整型

整型驗證器全部以"Int"開頭。

A.2 浮點型

內部一律使用double來處理

A.3 bool型

A.4 字串型

A.5 陣列型

A.6 物件型

A.7 檔案型

A.8 日期和時間型

A.9 條件判斷型

在一條驗證規則中，條件驗證器必須在其它驗證器前面，多個條件驗證器可以串聯。

注意，條件判斷中的“條件”一般是檢測另外一個引數的值，而當前引數的值是由串聯在條件判斷驗證器後面的其它驗證器來驗證。