Yii CDbCriteria 查詢條件完整用法大全

CDbCriteria 簡介

CDbCriteria 是 Yii 框架中用於構建複雜查詢條件的核心類，提供了豐富的方法來替代原生 SQL 的 WHERE、JOIN、ORDER、LIMIT 等子句，支援參數綁定、關聯查詢、分頁排序等進階功能。本文整理最常用的查詢條件用法。

基本條件構建

1. addCondition() - 基本 WHERE 條件

$criteria = new CDbCriteria;
$criteria->addCondition("MACID=464");           // WHERE MACID=464
$criteria->addCondition('id=1', 'OR');          // OR 條件：WHERE ... OR id=1

2. addInCondition() / addNotInCondition() - IN / NOT IN

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

3. addSearchCondition() - 模糊搜尋 (LIKE)

$criteria->addSearchCondition('link', '裸體');  
// WHERE link LIKE '%裸體%'

4. addBetweenCondition() - 區間查詢

$criteria->addBetweenCondition('id', 10000, 10005);  
// WHERE id BETWEEN 10000 AND 10005

5. compare() - 智慧比較

$criteria->compare('id', 1);        
// 自動判斷：單值用 addCondition，陣列用 addInCondition

參數綁定與公共屬性

參數綁定（防 SQL 注入）

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

常用公共屬性

$criteria->select = 'id, MACID, type';        // SELECT 欄位，預設 *
$criteria->join = 'xxx';                       // JOIN 表
$criteria->with = 'xxx';                       // 呼叫 relations 關聯
$criteria->limit = 10;                         // LIMIT 10
$criteria->offset = 1;                         // OFFSET 1 (配合 limit 實現分頁)
$criteria->order = 'id DESC, MACID ASC';       // ORDER BY
$criteria->group = 'group_type';               // GROUP BY
$criteria->having = 'having 條件';             // HAVING
$criteria->distinct = FALSE;                   // DISTINCT 查詢

實戰範例：搭配 CActiveDataProvider

return new CActiveDataProvider('visitlog', array(
    'criteria' => $criteria,
));

進階技巧

多條件組合

$criteria->addCondition('status=1');
$criteria->addInCondition('type', array(1,2,3));
$criteria->addSearchCondition('title', $keyword);
$criteria->addBetweenCondition('create_time', $start, $end);

子查詢與表別名

$criteria->select = 't.*, u.username';
$criteria->join = 'LEFT JOIN user u ON t.user_id = u.id';
$criteria->condition = 't.status=1 AND u.status=1';

動態條件構建

$criteria = new CDbCriteria;
if (!empty($search['keyword'])) {
    $criteria->addSearchCondition('title', $search['keyword']);
}
if (!empty($search['category'])) {
    $criteria->addCondition('category_id = :cat');
    $criteria->params[':cat'] = $search['category'];
}
if (!empty($search['date_range'])) {
    $criteria->addBetweenCondition('create_time', $search['start'], $search['end']);
}

注意事項

• 表別名：主表預設別名為 `t`，關聯表使用關聯名稱作為別名
• 參數陣列：`params` 鍵名需包含冒號（如 `:id`），值自動轉義
• 分頁配合：`limit` + `offset` 搭配 `CPagination` 使用
• 關聯預載：`with` 指定的關聯需在 Model 的 `relations()` 中定義

CDbCriteria 是 Yii 查詢構建的核心工具，熟練掌握可大幅減少手寫 SQL，提升代碼可維護性與安全性。