Yii2 驗證器體系全景指南
Yii2 提供豐富的內建驗證器（yii\validators\Validator 子類），涵蓋資料類型、格式、業務規則、檔案上傳、資料庫唯一性等場景。本文按功能分類詳細列舉所有核心驗證器用法、參數與實戰範例。
驗證器宣告語法
public function rules() {
return [
[['email', 'password'], 'required'],
['password', 'string', 'min' => 6],
// 格式：[屬性清單, 驗證器名稱, 參數陣列]
];
}
驗證器分類完整對照表
數值型驗證器
| 驗證器 | 類別 | 用途 | 關鍵參數 |
|---|
integer | NumberValidator | 整數驗證 | min, max |
double / number | NumberValidator | 浮點數驗證 | min, max |
格式型驗證器
| 驗證器 | 類別 | 用途 | 關鍵參數 |
|---|
date | DateValidator | 日期格式 | format, timestampAttribute |
email | EmailValidator | 電子郵件 | enableIDN, checkDNS |
url | UrlValidator | URL 格式 | validSchemes, defaultScheme |
資料處理型驗證器
| 驗證器 | 類別 | 用途 | 關鍵參數 |
|---|
filter | FilterValidator | 資料過濾/轉換 | filter (callable) |
trim | FilterValidator | 去除首尾空白 | pattern (自訂字元) |
檔案上傳驗證器
| 驗證器 | 類別 | 用途 | 關鍵參數 |
|---|
file | FileValidator | 通用檔案 | extensions, maxSize, mimeTypes |
image | ImageValidator | 圖片專用 | minWidth, maxWidth, minHeight, maxHeight |
比較與範圍驗證器
| 驗證器 | 類別 | 用途 | 關鍵參數 |
|---|
compare | CompareValidator | 兩值比較 | compareAttribute, operator (==, ===, >, <, >=, <=, !=) |
in | RangeValidator | 值在列表中 | range, strict, not |
exist | ExistValidator | 資料庫存在性 | targetClass, targetAttribute, filter |
unique | UniqueValidator | 資料庫唯一性 | targetClass, targetAttribute, filter |
字串與布林驗證器
| 驗證器 | 類別 | 用途 | 關鍵參數 |
|---|
string | StringValidator | 長度驗證 | min, max, length, encoding |
boolean | BooleanValidator | 布林值 | trueValue, falseValue, strict |
特殊用途驗證器
| 驗證器 | 類別 | 用途 | 關鍵參數 |
|---|
default | DefaultValueValidator | 設定預設值 | value, when (callable) |
required | RequiredValidator | 必填檢查 | requiredValue, strict, when, whenClient |
captcha | CaptchaValidator | 驗證碼 | captchaAction, caseSensitive |
match | RegularExpressionValidator | 正則表達式 | pattern, not |
safe | SafeValidator | 標記安全屬性 | 無參數，僅用於大量賦值白名單 |
進階用法範例
條件式驗證
['status', 'in', 'range' => [1,2,3], 'when' => function($model) {
return $model->scenario === 'admin';
}]
自訂驗證器
class PhoneValidator extends Validator {
public function validateAttribute($model, $attribute) {
if (!preg_match('/^09\d{8}$/', $model->$attribute)) {
$this->addError($model, $attribute, '手機格式錯誤');
}
}
}
// 使用
['phone', PhoneValidator::className()]
多欄位唯一性
[['first_name', 'last_name'], 'unique', 'targetAttribute' => ['first_name', 'last_name']]
驗證器執行順序與場景
- 依
rules() 陣列順序執行
on 參數指定場景（create, update, 自訂）except 排除場景skipOnEmpty, skipOnError 控制流程
總結
Yii2 驗證器體系完整覆蓋從基礎資料類型到複雜業務規則的驗證需求。善用內建驗證器組合與條件式參數，能大幅減少自訂驗證碼，提升程式碼可讀性與維護性。match 正則驗證器為萬用補位，但優先使用語義化驗證器以利文檔化。
