Yii CModel 規則驗證與錯誤訊息獲取完整指南

Yii CModel 規則驗證與錯誤訊息獲取完整指南

在 Yii 框架中，CModel 類別提供了強大的資料驗證機制。透過在模型中定義 rules() 方法，我們可以宣告欄位的驗證規則，並在控制器中輕鬆執行驗證與取得錯誤訊息。本文將系統性地介紹規則定義、驗證流程、錯誤獲取方式，以及視圖層的錯誤顯示技巧。

一、在 Model 中定義驗證規則

驗證規則以陣列形式回傳，每個子陣列代表一條規則。基本格式為：array('欄位清單', '驗證器名稱', '參數鍵值對...')。

public function rules() {
    return array(
        // 必填驗證
        array('Name, Email', 'required'),
        // 唯一值驗證，自訂錯誤訊息，{value} 會被替換為使用者輸入的值
        array('Email', 'unique', 'message' => '{value} 已被註冊'),
        // 長度驗證
        array('username', 'length', 'min' => 3, 'max' => 12),
        // 比較驗證（如密碼確認），可指定場景
        array('password', 'compare', 'compareAttribute' => 'password2', 'on' => 'register'),
        // 數值驗證，僅允許整數
        array('Price', 'numerical', 'integerOnly' => true),
        // 範圍驗證
        array('status', 'in', 'range' => array(1, 2, 3)),
        // 正則表達式驗證
        array('tags', 'match', 'pattern' => '/^[\w\s,]+$/', 'message' => '標籤只能包含字母、數字、底線、空格和逗號'),
        // 自訂驗證方法
        array('tags', 'normalizeTags'),
        // 安全屬性（可大量賦值），指定場景
        array('title, status', 'safe', 'on' => 'search'),
    );
}

二、控制器中執行驗證與獲取錯誤

典型流程：實例化模型 → 大量賦值屬性 → 呼叫 validate() → 根據結果處理。

$model = new MyModel(); // 實例化對應資料表的模型類別
$model->attributes = $_POST['MyModel']; // 僅賦值 rules 中標記為 safe 的欄位

if ($model->validate()) {
    // 驗證通過，執行儲存或其他邏輯
    $model->save();
} else {
    // 驗證失敗，獲取錯誤訊息
    $allErrors = $model->getErrors();        // 取得所有欄位錯誤，回傳陣列：array('欄位名' => array('錯誤1', '錯誤2'))
    $emailErrors = $model->getErrors('Email'); // 取得指定欄位的所有錯誤訊息陣列
    $firstEmailError = $model->getError('Email'); // 取得指定欄位的第一條錯誤訊息（字串）
}

• getErrors()：回傳所有驗證失敗欄位的錯誤訊息二維陣列。
• getErrors('fieldName')：回傳該欄位的錯誤訊息一維陣列。
• getError('fieldName')：回傳該欄位的第一條錯誤訊息字串，若無錯誤則回傳空字串。

三、視圖層顯示錯誤摘要

Yii 內建 CHtml::errorSummary() 或 CActiveForm::errorSummary() 可快速輸出所有錯誤訊息的無序清單（<ul><li>），樣式可透過 CSS 自訂。

<?php echo $form->errorSummary($model); ?>

若需自訂輸出格式，可迭代 $model->getErrors() 手動渲染。

四、常見問答

Q: 如何將表單錯誤訊息存為字串？

A: 直接使用 CHtml::errorSummary($model)，它會回傳包含 HTML 標籤的字串，可直接指派給變數或記錄日誌。

Q: Yii 表單驗證的完整流程參考？

A: 參考官方 Blog Demo 中的 SiteController::actionContact()：

1. 判斷 isset($_POST['ContactForm']) 確認表單提交。
2. $model->attributes = $_POST['ContactForm'] 賦值。
3. if ($model->validate()) 執行驗證，失敗則重新渲染視圖，視圖中 $form->errorSummary($model) 會自動顯示錯誤。
4. 成功則發送郵件、設定快閃訊息並重導向。

五、預設驗證器速查表

Yii 內建多個驗證器別名，對應具體類別：

每個驗證器支援通用屬性：message（自訂錯誤訊息）、on（適用場景）、allowEmpty（允許空值）、skipOnError（發生錯誤跳過後續規則）等。