Yii 2.0 ActiveRecord 增刪改查 (CRUD) 核心操作速查手冊

Yii 2.0 ActiveRecord 提供流暢的查詢構建器與對象映射，本文匯總最常用的 CRUD 操作代碼片段，涵蓋查詢、新增、更新、刪除、聚合、原生 SQL、事務、關聯查詢，適合作為開發時的桌面速查卡。

查詢操作

use app\models\User;

// 全部
$users = User::find()->all();

// 主鍵查單條
$user = User::findOne($id);           // 等同 find()->where(['id'=>$id])->one()
$user = User::findOne(['id'=>$id, 'status'=>1]);

// 條件查單條
$user = User::find()->where(['name'=>'ttt'])->one();

// 條件查多條
$users = User::find()->where(['name'=>'ttt'])->all();

// 原生 SQL 查詢
$users = User::findBySql('SELECT * FROM user WHERE status=1')->all();
$user  = User::findBySql('SELECT * FROM user WHERE id=1')->one();

// 連續條件
$users = User::find()
    ->where(['status'=>1])
    ->andWhere(['>', 'age', 18])
    ->orWhere(['role'=>'admin'])
    ->all();

// 聚合統計
$count = User::find()->where(['sex'=>'女', 'age'=>18])->count('id');
$count = User::find()->count();
$avgAge = User::find()->average('age');
$minAge = User::find()->min('age');
$maxAge = User::find()->max('age');

// 純量/列
$scalar = User::find()->select('count(*)')->scalar(); // 單值
$ids    = User::find()->select('id')->column();       // 一維陣列 [1,2,3...]
$exists = User::find()->where(['email'=>'a@b.com'])->exists(); // bool

// 分組
$groups = User::find()->groupBy('department_id')->all();

新增操作

$user = new User();
$user->username = '新用戶';
$user->email    = 'new@example.com';
$user->setPassword('secret123');
$user->generateAuthKey();
$user->save(); // 自動判斷是 INSERT

// 批量新增（單條 INSERT ... VALUES (),(),()）
$rows = [
    ['username'=>'a', 'email'=>'a@x.com'],
    ['username'=>'b', 'email'=>'b@x.com'],
];
$user->insertMultiple($rows); // 返回影響行數

更新操作

$user = User::findOne(1);
$user->email = 'updated@example.com';
$user->save(); // 自動判斷 UPDATE

// 靜態批量更新（不載入模型）
User::updateAll(
    ['status' => 0],                    // SET 字段
    ['>', 'last_login', strtotime('-1 year')] // WHERE 條件
);

// 按主鍵批量更新
User::updateAllCounters(
    ['login_count' => 1],               // 計數器增量
    ['status' => 1]                     // WHERE
);

刪除操作

$user = User::findOne(1);
$user->delete(); // 單條刪除

// 靜態批量刪除
User::deleteAll('status = 0 AND last_login < :time', [':time' => strtotime('-1 year')]);
User::deleteAll(['id' => [1,2,3]]); // IN 陣列

事務控制

use yii\db\Transaction;

$transaction = \Yii::$app->db->beginTransaction();
try {
    $user = new User();
    $user->username = 'tx_user';
    $user->save();

    $profile = new Profile();
    $profile->user_id = $user->id;
    $profile->save();

    $transaction->commit();
} catch (\Exception $e) {
    $transaction->rollBack();
    throw $e;
} catch (\Throwable $e) { // PHP 7+
    $transaction->rollBack();
    throw $e;
}

// 簡寫：自動提交/回滾
\Yii::$app->db->transaction(function($db) {
    $user = new User();
    $user->save();
    // 任何異常自動回滾
});

關聯查詢

// 假設 User 有關聯方法：
// public function getPosts() { return $this->hasMany(Post::class, ['user_id'=>'id']); }
// public function getProfile() { return $this->hasOne(Profile::class, ['user_id'=>'id']); }

// 延遲加載
$user = User::findOne(1);
$posts = $user->posts;        // 執行 SQL 查詢 posts
$profile = $user->profile;    // 查詢 profile

// 急切加載：一條 SQL JOIN 獲取
$users = User::find()->with('posts', 'profile')->all();
foreach ($users as $u) {
    // $u->posts 已填充，無額外查詢
}

// 多層級急切加載
$users = User::find()->with([
    'posts.comments',           // Post -> Comment
    'posts.author.profile',     // Post -> User -> Profile
    'profile'                   // User -> Profile
])->all();

// 關聯條件過濾
$users = User::find()->with([
    'posts' => function($q) {
        $q->where(['status'=>1])->orderBy(['created_at'=>SORT_DESC])->limit(5);
    }
])->all();

常用輔助方法

性能優化提示

• 只選需要的列： User::find()->select(['id','username'])->all()
• 避免 N+1： 列表頁必須用 with() 急切加載關聯。
• 大數據集用 each()： User::find()->each(100, function($user){ ... }); 游標逐批處理，防止內存溢出。
• 索引優化： where/join/order by 涉及的列建立索引。
• 緩存查詢結果： User::find()->cache(300)->all(); 需配置 cache 組件。

避坑指南

• findOne($id) 參數為陣列時視為條件，非主鍵值；純標量才視為主鍵。
• save() 返回 false 時必須檢查 getErrors()，否則靜默失敗。
• updateAll()/deleteAll() 不觸發 beforeSave/afterSave 等生命周期事件。
• 關聯屬性名與表字段重名會導致遮蔽，命名建議用 getPosts() 對應 posts 關聯，字段用 post_count。
• 事務嵌套需開啟 Transaction::REQUIRED，否則內層提交會真正提交。

將此速查手冊保存至 IDE Snippets 或團隊 Wiki，新人上手、老手複查都能節省大量翻文檔時間。