核心驗證器（Core Validators） · Yii 2.0 權威指南

# 核心驗證器（Core Validators） Yii 提供一系列常用的核心驗證器，主要存在于?`yii\validators`?命名空間之下。為了避免使用冗長的類名，你可以直接用**昵稱**來指定相應的核心驗證器。比如你可以用?`required`?昵稱代指 yii\validators\RequiredValidator 類： ~~~ public function rules() { return [ [['email', 'password'], 'required'], ]; } ~~~ yii\validators\Validator::builtInValidators 屬性聲明了所有被支持的驗證器昵稱。下面，我們將詳細介紹每一款驗證器的主要用法和屬性。 yii\validators\BooleanValidator ~~~ [ // 檢查 "selected" 是否為 0 或 1，無視數據類型 ['selected', 'boolean'], // 檢查 "deleted" 是否為布爾類型，即 true 或 false ['deleted', 'boolean', 'trueValue' => true, 'falseValue' => false, 'strict' => true], ] ~~~ 該驗證器檢查輸入值是否為一個布爾值。 * `trueValue`：代表**真**的值。默認為?`'1'`。 * `falseValue`：代表**假**的值。默認為?`'0'`。 * `strict`：是否要求待測輸入必須嚴格匹配?`trueValue`?或?`falseValue`。默認為?`false`。 > 注意：因為通過 HTML 表單傳遞的輸入數據都是字符串類型，所以一般情況下你都需要保持 yii\validators\BooleanValidator::strict 屬性為假。 yii\captcha\CaptchaValidator ~~~ [ ['verificationCode', 'captcha'], ] ~~~ 該驗證器通常配合 yii\captcha\CaptchaAction 以及 yii\captcha\Captcha 使用，以確保某一輸入與 yii\captcha\Captcha 小部件所顯示的驗證代碼（verification code）相同。 * `caseSensitive`：對驗證代碼的比對是否要求大小寫敏感。默認為 false。 * `captchaAction`：指向用于渲染 CAPTCHA 圖片的 yii\captcha\CaptchaAction 的?[路由](http://www.yiichina.com/doc/guide/2.0/structure-controllers#routes)。默認為?`'site/captcha'`。 * `skipOnEmpty`：當輸入為空時，是否跳過驗證。默認為 false，也就是輸入值為必需項。 yii\validators\CompareValidator ~~~ [ // 檢查 "password" 特性的值是否與 "password_repeat" 的值相同 ['password', 'compare'], // 檢查年齡是否大于等于 30 ['age', 'compare', 'compareValue' => 30, 'operator' => '>='], ] ~~~ 該驗證器比較兩個特定輸入值之間的關系是否與?`operator`?屬性所指定的相同。 * `compareAttribute`：用于與原特性相比較的特性名稱。當該驗證器被用于驗證某目標特性時，該屬性會默認為目標屬性加后綴`_repeat`。舉例來說，若目標特性為?`password`，則該屬性默認為?`password_repeat`。 * `compareValue`：用于與輸入值相比較的常量值。當該屬性與?`compareAttribute`?屬性同時被指定時，該屬性優先被使用。 * `operator`：比較操作符。默認為?`==`，意味著檢查輸入值是否與?`compareAttribute`?或?`compareValue`?的值相等。該屬性支持如下操作符： * `==`：檢查兩值是否相等。比對為非嚴格模式。 * `===`：檢查兩值是否全等。比對為嚴格模式。 * `!=`：檢查兩值是否不等。比對為非嚴格模式。 * `!==`：檢查兩值是否不全等。比對為嚴格模式。 * `>`：檢查待測目標值是否大于給定被測值。 * `>=`：檢查待測目標值是否大于等于給定被測值。 * `<`：檢查待測目標值是否小于給定被測值。 * `<=`：檢查待測目標值是否小于等于給定被測值。 yii\validators\DateValidator ~~~ [ [['from', 'to'], 'date'], ] ~~~ 該驗證器檢查輸入值是否為適當格式的 date，time，或者 datetime。另外，它還可以幫你把輸入值轉換為一個 UNIX 時間戳并保存到 yii\validators\DateValidator::timestampAttribute 屬性所指定的特性里。 * `format`：待測的日期/時間格式。請參考?[date_create_from_format() 相關的 PHP 手冊](http://www.php.net/manual/zh/datetime.createfromformat.php)了解設定格式字符串的更多細節。默認值為`'Y-m-d'`。 * `timestampAttribute`：用于保存用輸入時間/日期轉換出來的 UNIX 時間戳的特性。 yii\validators\DefaultValueValidator ~~~ [ // 若 "age" 為空，則將其設為 null ['age', 'default', 'value' => null], // 若 "country" 為空，則將其設為 "USA" ['country', 'default', 'value' => 'USA'], // 若 "from" 和 "to" 為空，則分別給他們分配自今天起，3 天后和 6 天后的日期。 [['from', 'to'], 'default', 'value' => function ($model, $attribute) { return date('Y-m-d', strtotime($attribute === 'to' ? '+3 days' ：'+6 days')); }], ] ~~~ 該驗證器并不進行數據驗證。而是，給為空的待測特性分配默認值。 * `value`：默認值，或一個返回默認值的 PHP Callable 對象（即回調函數）。它們會分配給檢測為空的待測特性。PHP 回調方法的樣式如下： ~~~ function foo($model, $attribute) { // ... 計算 $value ... return $value; } ~~~ > 補充：如何判斷待測值是否為空，被寫在另外一個話題的[處理空輸入](http://www.yiichina.com/doc/guide/2.0/input-validation#handling-empty-inputs)章節。 yii\validators\NumberValidator ~~~ [ // 檢查 "salary" 是否為浮點數 ['salary', 'double'], ] ~~~ 該驗證器檢查輸入值是否為雙精度浮點數。他等效于?[number](http://www.yiichina.com/doc/guide/2.0/tutorial-core-validators#number)?驗證器。 * `max`：上限值（含界點）。若不設置，則驗證器不檢查上限。 * `min`：下限值（含界點）。若不設置，則驗證器不檢查下限。 yii\validators\EmailValidator ~~~ [ // 檢查 "email" 是否為有效的郵箱地址 ['email', 'email'], ] ~~~ 該驗證器檢查輸入值是否為有效的郵箱地址。 * `allowName`：檢查是否允許帶名稱的電子郵件地址 (e.g.?`張三 <John.san@example.com>`)。默認為 false。 * `checkDNS`：檢查郵箱域名是否存在，且有沒有對應的 A 或 MX 記錄。不過要知道，有的時候該項檢查可能會因為臨時性 DNS 故障而失敗，哪怕它其實是有效的。默認為 false。 * `enableIDN`：驗證過程是否應該考慮 IDN（internationalized domain names，國際化域名，也稱多語種域名，比如中文域名）。默認為 false。要注意但是為使用 IDN 驗證功能，請先確保安裝并開啟?`intl`?PHP 擴展，不然會導致拋出異常。 yii\validators\ExistValidator ~~~ [ // a1 需要在 "a1" 特性所代表的字段內存在 ['a1', 'exist'], // a1 必需存在，但檢驗的是 a1 的值在字段 a2 中的存在性 ['a1', 'exist', 'targetAttribute' => 'a2'], // a1 和 a2 的值都需要存在，且它們都能收到錯誤提示 [['a1', 'a2'], 'exist', 'targetAttribute' => ['a1', 'a2']], // a1 和 a2 的值都需要存在，只有 a1 能接收到錯誤信息 ['a1', 'exist', 'targetAttribute' => ['a1', 'a2']], // 通過同時在 a2 和 a3 字段中檢查 a2 和 a1 的值來確定 a1 的存在性 ['a1', 'exist', 'targetAttribute' => ['a2', 'a1' => 'a3']], // a1 必需存在，若 a1 為數組，則其每個子元素都必須存在。 ['a1', 'exist', 'allowArray' => true], ] ~~~ 該驗證器檢查輸入值是否在某表字段中存在。它只對[活動記錄](http://www.yiichina.com/doc/guide/2.0/db-active-record)類型的模型類特性起作用，能支持對一個或多過字段的驗證。 * `targetClass`：用于查找輸入值的目標?[AR](http://www.yiichina.com/doc/guide/2.0/db-active-record)?類。若不設置，則會使用正在進行驗證的當前模型類。 * `targetAttribute`：用于檢查輸入值存在性的?`targetClass`?的模型特性。 * 若不設置，它會直接使用待測特性名（整個參數數組的首元素）。 * 除了指定為字符串以外，你也可以用數組的形式，同時指定多個用于驗證的表字段，數組的鍵和值都是代表字段的特性名，值表示?`targetClass`?的待測數據源字段，而鍵表示當前模型的待測特性名。 * 若鍵和值相同，你可以只指定值。（如:`['a2']`?就代表?`['a2'=>'a2']`） * `filter`：用于檢查輸入值存在性必然會進行數據庫查詢，而該屬性為用于進一步篩選該查詢的過濾條件。可以為代表額外查詢條件的字符串或數組（關于查詢條件的格式，請參考 yii\db\Query::where()）；或者樣式為?`function ($query)`?的匿名函數，`$query`參數為你希望在該函數內進行修改的 yii\db\Query 對象。 * `allowArray`：是否允許輸入值為數組。默認為 false。若該屬性為 true 且輸入值為數組，則數組的每個元素都必須在目標字段中存在。值得注意的是，若用吧?`targetAttribute`?設為多元素數組來驗證被測值在多字段中的存在性時，該屬性不能設置為 true。 > 譯注：[exist](http://www.yiichina.com/doc/guide/2.0/tutorial-core-validators#exist)?和?[unique](http://www.yiichina.com/doc/guide/2.0/tutorial-core-validators#unique)?驗證器的機理和參數都相似，有點像一體兩面的陰和陽。 > > * 他們的區別是 exist 要求?`targetAttribute`?鍵所代表的的屬性在其值所代表字段中找得到；而 unique 正相反，要求鍵所代表的的屬性不能在其值所代表字段中被找到。 > * 從另一個角度來理解：他們都會在驗證的過程中執行數據庫查詢，查詢的條件即為where $v=$k (假設?`targetAttribute`?的其中一對鍵值對為?`$k => $v`)。unique 要求查詢的結果數?`$count==0`，而 exist 則要求查詢的結果數?`$count>0` > * 最后別忘了，unique 驗證器不存在?`allowArray`?屬性哦。 yii\validators\FileValidator ~~~ [ // 檢查 "primaryImage" 是否為 PNG, JPG 或 GIF 格式的上傳圖片。 // 文件大小必須小于 1MB ['primaryImage', 'file', 'extensions' => ['png', 'jpg', 'gif'], 'maxSize' => 1024*1024*1024], ] ~~~ 該驗證器檢查輸入值是否為一個有效的上傳文件。 * `extensions`：可接受上傳的文件擴展名列表。它可以是數組，也可以是用空格或逗號分隔各個擴展名的字符串 (e.g. "gif, jpg")。擴展名大小寫不敏感。默認為 null，意味著所有擴展名都被接受。 * `mimeTypes`：可接受上傳的 MIME 類型列表。它可以是數組，也可以是用空格或逗號分隔各個 MIME 的字符串 (e.g. "image/jpeg, image/png")。 Mime 類型名是大小寫不敏感的。默認為 null，意味著所有 MIME 類型都被接受。 * `minSize`：上傳文件所需最少多少 Byte 的大小。默認為 null，代表沒有下限。 * `maxSize`：上傳文件所需最多多少 Byte 的大小。默認為 null，代表沒有上限。 * `maxFiles`：給定特性最多能承載多少個文件。默認為 1，代表只允許單文件上傳。若值大于一，那么輸入值必須為包含最多`maxFiles`?個上傳文件元素的數組。 * `checkExtensionByMimeType`：是否通過文件的 MIME 類型來判斷其文件擴展。若由 MIME 判定的文件擴展與給定文件的擴展不一樣，則文件會被認為無效。默認為 true，代表執行上述檢測。 `FileValidator`?通常與 yii\web\UploadedFile 共同使用。請參考?[文件上傳](http://www.yiichina.com/doc/guide/2.0/input-file-upload)章節來了解有關文件上傳與上傳文件的檢驗的全部內容。 yii\validators\FilterValidator ~~~ [ // trim 掉 "username" 和 "email" 輸入 [['username', 'email'], 'filter', 'filter' => 'trim', 'skipOnArray' => true], // 標準化 "phone" 輸入 ['phone', 'filter', 'filter' => function ($value) { // 在此處標準化輸入的電話號碼 return $value; }], ] ~~~ 該驗證器并不進行數據驗證。而是，給輸入值應用一個濾鏡，并在檢驗過程之后把它賦值回特性變量。 * `filter`：用于定義濾鏡的 PHP 回調函數。可以為全局函數名，匿名函數，或其他。該函數的樣式必須是?`function ($value) { return $newValue; }`。該屬性不能省略，必須設置。 * `skipOnArray`：是否在輸入值為數組時跳過濾鏡。默認為 false。請注意如果濾鏡不能處理數組輸入，你就應該把該屬性設為 true。否則可能會導致 PHP Error 的發生。 > 技巧：如果你只是想要用 trim 處理下輸入值，你可以直接用?[trim](http://www.yiichina.com/doc/guide/2.0/tutorial-core-validators#trim)?驗證器的。 yii\validators\ImageValidator ~~~ [ // 檢查 "primaryImage" 是否為適當尺寸的有效圖片 ['primaryImage', 'image', 'extensions' => 'png, jpg', 'minWidth' => 100, 'maxWidth' => 1000, 'minHeight' => 100, 'maxHeight' => 1000, ], ] ~~~ 該驗證器檢查輸入值是否為代表有效的圖片文件。它繼承自?[file](http://www.yiichina.com/doc/guide/2.0/tutorial-core-validators#file)?驗證器，并因此繼承有其全部屬性。除此之外，它還支持以下為圖片檢驗而設的額外屬性： * `minWidth`：圖片的最小寬度。默認為 null，代表無下限。 * `maxWidth`：圖片的最大寬度。默認為 null，代表無上限。 * `minHeight`：圖片的最小高度。默認為 null，代表無下限。 * `maxHeight`：圖片的最大高度。默認為 null，代表無上限。 yii\validators\RangeValidator ~~~ [ // 檢查 "level" 是否為 1、2 或 3 中的一個 ['level', 'in', 'range' => [1, 2, 3]], ] ~~~ 該驗證器檢查輸入值是否存在于給定列表的范圍之中。 * `range`：用于檢查輸入值的給定值列表。 * `strict`：輸入值與給定值直接的比較是否為嚴格模式（也就是類型與值都要相同，即全等）。默認為 false。 * `not`：是否對驗證的結果取反。默認為 false。當該屬性被設置為 true，驗證器檢查輸入值是否**不在**給定列表內。 * `allowArray`：是否接受輸入值為數組。當該值為 true 且輸入值為數組時，數組內的每一個元素都必須在給定列表內存在，否則返回驗證失敗。 yii\validators\NumberValidator ~~~ [ // 檢查 "age" 是否為整數 ['age', 'integer'], ] ~~~ 該驗證器檢查輸入值是否為整形。 * `max`：上限值（含界點）。若不設置，則驗證器不檢查上限。 * `min`：下限值（含界點）。若不設置，則驗證器不檢查下限。 yii\validators\RegularExpressionValidator ~~~ [ // 檢查 "username" 是否由字母開頭，且只包含單詞字符 ['username', 'match', 'pattern' => '/^[a-z]\w*$/i'] ] ~~~ 該驗證器檢查輸入值是否匹配指定正則表達式。 * `pattern`：用于檢測輸入值的正則表達式。該屬性是必須的，若不設置則會拋出異常。 * `not`：是否對驗證的結果取反。默認為 false，代表輸入值匹配正則表達式時驗證成功。如果設為 true，則輸入值不匹配正則時返回匹配成功。 yii\validators\NumberValidator ~~~ [ // 檢查 "salary" 是否為數字 ['salary', 'number'], ] ~~~ 該驗證器檢查輸入值是否為數字。他等效于?[double](http://www.yiichina.com/doc/guide/2.0/tutorial-core-validators#double)?驗證器。 * `max`：上限值（含界點）。若不設置，則驗證器不檢查上限。 * `min`：下限值（含界點）。若不設置，則驗證器不檢查下限。 yii\validators\RequiredValidator ~~~ [ // 檢查 "username" 與 "password" 是否為空 [['username', 'password'], 'required'], ] ~~~ 該驗證器檢查輸入值是否為空，還是已經提供了。 * `requiredValue`：所期望的輸入值。若沒設置，意味著輸入不能為空。 * `strict`：檢查輸入值時是否檢查類型。默認為 false。當沒有設置?`requiredValue`?屬性時，若該屬性為 true，驗證器會檢查輸入值是否嚴格為 null；若該屬性設為 false，該驗證器會用一個更加寬松的規則檢驗輸入值是否為空。當設置了?`requiredValue`?屬性時，若該屬性為 true，輸入值與?`requiredValue`?的比對會同時檢查數據類型。 > 補充：如何判斷待測值是否為空，被寫在另外一個話題的[處理空輸入](http://www.yiichina.com/doc/guide/2.0/input-validation#handling-empty-inputs)章節。 yii\validators\SafeValidator ~~~ [ // 標記 "description" 為安全特性 ['description', 'safe'], ] ~~~ 該驗證器并不進行數據驗證。而是把一個特性標記為[安全特性](http://www.yiichina.com/doc/guide/2.0/structure-models#safe-attributes)。 yii\validators\StringValidator ~~~ [ // 檢查 "username" 是否為長度 4 到 24 之間的字符串 ['username', 'string', 'length' => [4, 24]], ] ~~~ 該驗證器檢查輸入值是否為特定長度的字符串。并檢查特性的值是否為某個特定長度。 * `length`：指定待測輸入字符串的長度限制。該屬性可以被指定為以下格式之一： * 證書：the exact length that the string should be of; * 單元素數組：代表輸入字符串的最小長度 (e.g.?`[8]`)。這會重寫?`min`?屬性。 * 包含兩個元素的數組：代表輸入字符串的最小和最大長度(e.g.?`[8, 128]`)。這會同時重寫?`min`?和?`max`?屬性。 * `min`：輸入字符串的最小長度。若不設置，則代表不設下限。 * `max`：輸入字符串的最大長度。若不設置，則代表不設上限。 * `encoding`：待測字符串的編碼方式。若不設置，則使用應用自身的 yii\base\Application::charset 屬性值，該值默認為?`UTF-8`。 yii\validators\FilterValidator ~~~ [ // trim 掉 "username" 和 "email" 兩側的多余空格 [['username', 'email'], 'trim'], ] ~~~ 該驗證器并不進行數據驗證。而是，trim 掉輸入值兩側的多余空格。注意若該輸入值為數組，那它會忽略掉該驗證器。 yii\validators\UniqueValidator ~~~ [ // a1 需要在 "a1" 特性所代表的字段內唯一 ['a1', 'unique'], // a1 需要唯一，但檢驗的是 a1 的值在字段 a2 中的唯一性 ['a1', 'unique', 'targetAttribute' => 'a2'], // a1 和 a2 的組合需要唯一，且它們都能收到錯誤提示 [['a1', 'a2'], 'unique', 'targetAttribute' => ['a1', 'a2']], // a1 和 a2 的組合需要唯一，只有 a1 能接收錯誤提示 ['a1', 'unique', 'targetAttribute' => ['a1', 'a2']], // 通過同時在 a2 和 a3 字段中檢查 a2 和 a3 的值來確定 a1 的唯一性 ['a1', 'unique', 'targetAttribute' => ['a2', 'a1' => 'a3']], ] ~~~ 該驗證器檢查輸入值是否在某表字段中唯一。它只對[活動記錄](http://www.yiichina.com/doc/guide/2.0/db-active-record)類型的模型類特性起作用，能支持對一個或多過字段的驗證。 * `targetClass`：用于查找輸入值的目標?[AR](http://www.yiichina.com/doc/guide/2.0/db-active-record)?類。若不設置，則會使用正在進行驗證的當前模型類。 * `targetAttribute`：用于檢查輸入值唯一性的?`targetClass`?的模型特性。 * 若不設置，它會直接使用待測特性名（整個參數數組的首元素）。 * 除了指定為字符串以外，你也可以用數組的形式，同時指定多個用于驗證的表字段，數組的鍵和值都是代表字段的特性名，值表示?`targetClass`?的待測數據源字段，而鍵表示當前模型的待測特性名。 * 若鍵和值相同，你可以只指定值。（如:`['a2']`?就代表?`['a2'=>'a2']`） * `filter`：用于檢查輸入值唯一性必然會進行數據庫查詢，而該屬性為用于進一步篩選該查詢的過濾條件。可以為代表額外查詢條件的字符串或數組（關于查詢條件的格式，請參考 yii\db\Query::where()）；或者樣式為?`function ($query)`?的匿名函數，`$query`參數為你希望在該函數內進行修改的 yii\db\Query 對象。 > 譯注：[exist](http://www.yiichina.com/doc/guide/2.0/tutorial-core-validators#exist)?和?[unique](http://www.yiichina.com/doc/guide/2.0/tutorial-core-validators#unique)?驗證器的機理和參數都相似，有點像一體兩面的陰和陽。 > > * 他們的區別是 exist 要求?`targetAttribute`?鍵所代表的的屬性在其值所代表字段中找得到；而 unique 正相反，要求鍵所代表的的屬性不能在其值所代表字段中被找到。 > * 從另一個角度來理解：他們都會在驗證的過程中執行數據庫查詢，查詢的條件即為where $v=$k (假設?`targetAttribute`?的其中一對鍵值對為?`$k => $v`)。unique 要求查詢的結果數?`$count==0`，而 exist 則要求查詢的結果數?`$count>0` > * 最后別忘了，unique 驗證器不存在?`allowArray`?屬性哦。 yii\validators\UrlValidator ~~~ [ // 檢查 "website" 是否為有效的 URL。若沒有 URI 方案，則給 "website" 特性加 "http://" 前綴 ['website', 'url', 'defaultScheme' => 'http'], ] ~~~ 該驗證器檢查輸入值是否為有效 URL。 * `validSchemes`：用于指定那些 URI 方案會被視為有效的數組。默認為?`['http', 'https']`，代表?`http`?和?`https`?URLs 會被認為有效。 * `defaultScheme`：若輸入值沒有對應的方案前綴，會使用的默認 URI 方案前綴。默認為 null，代表不修改輸入值本身。 * `enableIDN`：驗證過程是否應該考慮 IDN（internationalized domain names，國際化域名，也稱多語種域名，比如中文域名）。默認為 false。要注意但是為使用 IDN 驗證功能，請先確保安裝并開啟?`intl`?PHP 擴展，不然會導致拋出異常。