Yii 2 框架 Model 模型完整指南：從基礎屬性到進階驗證與最佳實踐

Yii 2 Model 模型核心概念

在 MVC 架構中，Model（模型）代表業務數據、規則與邏輯的核心物件。Yii 2 中的模型繼承自 yii\base\Model 或其子類，負責封裝單筆數據對象——可能是資料表的一行記錄，也可能是用戶提交的表單數據。每個模型屬性對應一個數據字段，並擁有標籤（Label）與驗證規則。

Yii 實現了兩類主要模型：

• 表單模型（CFormModel）：用於暫存用戶輸入數據，如登入表單的帳號密碼，數據處理後即可丟棄。
• Active Record (AR)：採用設計模式將資料庫操作物件化，每個 AR 實例對應資料表一行，屬性映射欄位，支援完整的 CRUD 操作。

基礎特性詳解

屬性定義與存取

繼承 yii\base\Model 時，所有非靜態公有成員變數自動成為屬性。支援物件屬性語法（$model->name）與陣列語法（$model['name']）雙重存取，並實作 ArrayAccess、ArrayIterator 介面，可直接迭代：

$model = new \app\models\ContactForm;
$model->name = 'example';  // 物件語法
$model['email'] = 'test@example.com';  // 陣列語法
foreach ($model as $name => $value) {
    echo "$name: $value\n";
}

屬性標籤與多國語言

預設自動將駝峰命名轉為標籤（firstName → First Name）。可覆寫 attributeLabels() 自訂，並結合 Yii::t() 實現多語系：

public function attributeLabels() {
    return [
        'name' => \Yii::t('app', 'Your name'),
        'email' => \Yii::t('app', 'Your email address'),
    ];
}

場景機制

模型可在不同場景下啟用不同屬性與驗證規則。例如 User 模型在 login 場景只需帳號密碼，register 場景則額外需要 Email。透過覆寫 scenarios() 定義：

public function scenarios() {
    return [
        'login' => ['username', 'password'],
        'register' => ['username', 'email', 'password'],
    ];
}

驗證規則

在 rules() 宣告規則，支援 required、email、string、integer 等內建驗證器，並可指定 on 限定場景：

public function rules() {
    return [
        [['name', 'email', 'subject', 'body'], 'required'],
        ['email', 'email'],
        [['username', 'password'], 'required', 'on' => 'login'],
    ];
}

批量賦值與安全屬性

單行程式碼 $model->attributes = $inputData 即可完成批量賦值。只有在當前場景的 scenarios() 列出的「安全屬性」才會被賦值。若需標記屬性為安全但不驗證，可使用 safe 驗證器；若需驗證但不允許批量賦值，在場景中加 ! 前綴（如 '!secret'）。

資料導出與欄位控制

toArray() 可將模型轉為陣列，預設輸出所有屬性。覆寫 fields() 可精確控制輸出欄位、重命名、甚至動態計算值；extraFields() 提供擴展欄位，需透過 toArray([], ['extraField']) 顯式請求。務必過濾敏感欄位（如密碼雜湊、Token）：

public function fields() {
    $fields = parent::fields();
    unset($fields['auth_key'], $fields['password_hash']);
    return $fields;
}

最佳實踐與架構建議

• 模型專注業務邏輯與驗證，不直接存取 $_GET/$_POST/Session，由控制器傳入數據。
• 避免在模型中嵌入 HTML 或展示邏輯，交由 View 處理。
• 大型系統建議採用「基類 + 具體類」分層：common\models\Post 定義共用規則，frontend\models\Post、backend\models\Post 分別繼承並擴展各自業務邏輯，降低耦合與維護成本。