Yii Framework CDbCriteria 常用方法總結與實戰技巧

Yii CDbCriteria 核心用法全解析

在 Yii 框架開發中，CDbCriteria 是構建複雜 SQL 查詢的核心類。它將 WHERE、ORDER、LIMIT、IN/NOT IN、LIKE 等常用 SQL 片段封裝為物件屬性與方法，使查詢邏輯更加規範、可讀性極強。本文系統整理其常用用法，並輔以實戰代碼示例。

基本實例化與條件構建

$criteria = new CDbCriteria();

常用條件方法

• addCondition()：添加基本 WHERE 條件，預設邏輯為 AND

  $criteria->addCondition("id = 1"); // WHERE id = 1
  $criteria->addCondition("id = 1", "OR"); // OR 條件

• addInCondition() / addNotInCondition()：IN / NOT IN 查詢

  $criteria->addInCondition('id', [1,2,3,4,5]); // WHERE id IN (1,2,3,4,5)
  $criteria->addNotInCondition('id', [1,2,3,4,5]); // WHERE id NOT IN (...)

• addSearchCondition()：模糊搜尋（自動加 %）

  $criteria->addSearchCondition('name', '分類'); // WHERE name LIKE '%分類%'

• addBetweenCondition()：範圍查詢

  $criteria->addBetweenCondition('id', 1, 4); // WHERE id BETWEEN 1 AND 4

• compare()：智慧比較，自動判斷標量或陣列

  $criteria->compare('id', 1); // 等同 addCondition
  $criteria->compare('id', [1,2,3]); // 自動轉為 addInCondition

參數綁定與安全查詢

$criteria->addCondition("id = :id");
$criteria->params[':id'] = 1; // 防 SQL 注入，推薦做法

查詢字段、關聯、分頁、排序

$criteria->select = 'id, parentid, name'; // 指定欄位，預選 *
$criteria->join = 'LEFT JOIN profile ON user.id = profile.user_id'; // 連表
$criteria->with = 'profile'; // 使用關聯關係
$criteria->limit = 10; // 取 10 條
$criteria->offset = 1; // 偏移 1，合併為 LIMIT 1,10
$criteria->order = 'created_at DESC, id ASC'; // 排序
$criteria->group = 'category_id'; // 分組
$criteria->having = 'COUNT(*) > 5'; // HAVING
$criteria->distinct = false; // 是否去重

進階應用：僅選取特定欄位

若只需部分欄位，可直接在 find() 或 findAll() 中傳入陣列：

User::model()->find([
    'select' => 'id, username',
    'condition' => 'status = 1'
]);

關於預存程序的說明

CDbCriteria 本身不直接支援呼叫預存程序，若需執行 CALL proc()，建議使用 DAO：

$sql = "CALL my_procedure()";
$data = Yii::app()->db->createCommand($sql)->queryAll();