Yii CDbCriteria 常用方法完整指南與實戰技巧

Yii CDbCriteria 常用方法完整指南與實戰技巧

在 Yii 框架開發中，CDbCriteria 是構建複雜資料庫查詢的核心類別。掌握其常用方法，能讓你輕鬆應對各種查詢場景，從簡單的條件篩選到複雜的多表關聯。本文將系統整理 CDbCriteria 的核心方法、屬性配置與實戰範例，助你提升查詢開發效率。

一、基本查詢條件構建

建立 CDbCriteria 物件後，可透過多種方法添加查詢條件：

$criteria = new CDbCriteria();

// 基本 WHERE 條件
$criteria->addCondition("id = 1");              // WHERE id = 1
$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 (1,2,3,4,5)

// OR 條件連接（預設為 AND）
$criteria->addCondition('id = 1', 'OR');        // 多條件時該條件以 OR 連接

// 模糊搜尋（自動加上 %）
$criteria->addSearchCondition('name', '分類');   // WHERE name LIKE '%分類%'

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

// 智慧比較：自動判斷標量或陣列
$criteria->compare('id', 1);                    // 等同 addCondition
$criteria->compare('id', [1,2,3]);              // 等同 addInCondition

二、參數綁定與安全查詢

為防止 SQL 注入，建議使用參數綁定方式：

$criteria->addCondition("id = :id");
$criteria->params[':id'] = 1;

三、常用公開屬性配置

CDbCriteria 提供豐富的公開屬性控制查詢行為：

// 欄位選擇（預設 *）
$criteria->select = 'id, parentid, name';

// 表關聯
$criteria->join = 'LEFT JOIN profile ON profile.user_id = t.id'; // 手動 JOIN
$criteria->with = 'profile';                                     // 使用關聯關係

// 分頁控制
$criteria->limit = 10;   // 取 10 筆，<0 表示不限制
$criteria->offset = 1;   // 配合 limit 實現 LIMIT 1,10

// 排序、分組、去重
$criteria->order = 'created_at DESC, id ASC';
$criteria->group = 'category_id';
$criteria->having = 'COUNT(*) > 5';
$criteria->distinct = false;

四、多表關聯查詢實戰

結合 alias、join 與 condition 實現複雜關聯：

$criteria = new CDbCriteria;
$criteria->alias = 'Invoice';
$criteria->join = 'LEFT JOIN Client ON Client.id = Invoice.clientId';
$criteria->condition = 'Client.businessId = ' . Yii::app()->userInfo->business;

五、最佳實踐建議

• 優先使用 params 參數綁定，避免直接拼接 SQL 字串
• 善用 with 載入關聯資料，減少 N+1 查詢問題
• 大量資料分頁時，設定合理的 limit 與 offset
• 複雜查詢可考慮使用 CDbCommand 直接撰寫 SQL 以獲得更好效能

掌握這些核心方法，你就能在 Yii 專案中靈活構建高效、安全的資料庫查詢。