Yii 的 CActiveRecord 模型透過 rules() 方法定義資料驗證規則，是確保資料完整性的第一道防線。本文系統整理 14 種常用核心驗證器的語法、參數與實戰範例，助你快速建立健壯的表單驗證邏輯。
public function rules() {
return array(
// 整數驗證
array('project_id, type_id, status_id, owner_id, requester_id', 'numerical', 'integerOnly'=>true),
// 長度限制
array('name', 'length', 'max'=>256),
array('description', 'length', 'max'=>2000),
// 安全屬性（大量賦值允許）
array('create_time, create_user_id, update_user_id, update_time', 'safe'),
// 搜尋場景專用屬性
array('id, name, description, project_id, type_id, status_id, owner_id', 'on'=>'search'),
);
}
| 驗證器 | 用途 | 關鍵參數 | 範例 |
|---|---|---|---|
| required | 必填欄位 | — | array('title,content','required') |
| match | 正則表達式 | pattern, allowEmpty, message | array('birthday','match','pattern'=>'%^\d{4}[-/.]\d{1,2}\1\d{1,2}$%','message'=>'日期格式錯誤') |
| Email 格式 | — | array('user_mail','email') |
|
| url | URL 格式 | — | array('user','url') |
| unique | 唯一性（資料庫） | caseSensitive, className, message | array('username','unique','caseSensitive'=>false,'className'=>'User','message'=>'用戶名已存在') |
| compare | 欄位一致性 | compareAttribute, message | array('repassword','compare','compareAttribute'=>'password','message'=>'兩次密碼不一致') |
| length | 字串長度 | min, max, is, encoding | array('name','length','max'=>256,'min'=>2) |
| in / range | 值在列表中 | range, strict | array('status','in','range'=>array(1,2,3)) |
| numerical | 數值型別 | integerOnly, min, max | array('age','numerical','integerOnly'=>true,'min'=>18) |
| captcha | 驗證碼 | — | array('verifyCode','captcha') |
| type | 型別檢查 | type (string, array, integer, float, date, time, datetime) | array('birth_date','type','type'=>'date','dateFormat'=>'yyyy-MM-dd') |
| file | 上傳檔案 | types, maxSize, minSize, tooLarge, tooSmall | array('avatar','file','types'=>'jpg,png','maxSize'=>1024*1024*2) |
| default | 設定預設值 | value, setOnEmpty | array('status','default','value'=>1,'setOnEmpty'=>true) |
| exist | 資料庫存在性 | className, attributeName, criteria | array('category_id','exist','className'=>'Category') |
| boolean | 布林值 | trueValue, falseValue, strict | array('is_active','boolean','trueValue'=>1,'falseValue'=>0) |
| date | 日期/時間 | format, timestampAttribute | array('expire_at','date','format'=>'yyyy-MM-dd HH:mm') |
| safe / unsafe | 大量賦值安全標記 | — | array('token','unsafe') 防止惡意賦值 |
使用 on 參數指定驗證場景：
array('email', 'required', 'on'=>'register'), // 註冊時必填
array('email', 'email', 'on'=>'register,profile'), // 註冊與編輯檔案都驗證格式
public function rules() {
return array(
array('custom_field', 'validateCustom'), // 方法名 validateCustom
);
}
public function validateCustom($attribute, $params) {
if ($this->$attribute !== 'expected') {
$this->addError($attribute, '自訂驗證失敗');
}
}
array('field', 'required', 'when'=>function($model){ return $model->scenario === 'admin'; })
熟練掌握這 14 種驗證器與進階用法，能讓你在幾分鐘內建立出企業級的表單驗證體系。建議收藏本文作為開發時的速查手冊！
