Использования CDbCriteria в Yii

yii CDbCriteria CDbCriteria - это набор правил, критериев, по которым строится запрос, обычно SQL. Например, сортировка - order by, смещение offset, ограничение - limit.

Может использоваться в методах ActiveRecord, например в: CActiveRecord::find и CActiveRecord::findAll.

Простой пример выборки, для модели Post:

$criteria=new CDbCriteria();

$criteria->compare('status',Post::STATUS_ACTIVE);

$criteria->addInCondition('id',array(1,2,3,4,5,6));

$posts = Post::model()->findAll($criteria);

Свойства CDbCriteria:

Название	Тип	Описание
alias	string	Псевдоним таблицы. Если не установлен, используется строка "t"
condition	string	Условие запроса. Добавляется в оператор WHERE в SQL-выражении. Например, "age>31 AND team=1"
distinct	boolean	Выбирать ли только неповторяющиеся строки данных. Если равно true, оператор SELECT будет изменен на SELECT DISTINCT
group	string	Правило группировки результатов запроса. Добавляется в оператор GROUP BY в SQL-выражении. Например, "projectID, teamID"
having	string	Выражение, выполняемое с оператором GROUP BY. Например, "SUM(revenue)<50000"
index	string	Имя AR-атрибута, значение которого должно использоваться в качестве индекса массива результата запроса. По умолчанию - null, т.е., массив результата будет иметь целочисленные индексы, начинающиеся с нуля
join	string	Правило объединения с другими таблицами. Добавляется в оператор JOIN в SQL-выражении. Например, "LEFT JOIN users ON users.id=authorID"
limit	integer	Mаксимальное количество возвращаемых записей. Если меньше 0, то ограничений нет
offset	integer	Смещение (начиная с нуля), с которого будут возвращаться записи. Если меньше 0, то выборка начинается от начала
order	string	Правило сортировки результатов запроса. Добавляется в оператор ORDER BY в SQL-выражении
paramCount	integer	Глобальный счетчик анонимных связанных параметров. Данный счетчик используется для генерации имен анонимных параметров
params	array	Список значений параметров запроса, индексированных по меткам параметров. Например, "array(':name'=>'Dan', ':age'=>31)"
scopes	mixed	Применяемая группа условий. Свойство имеет значение только если критерий передан в качестве параметра в один из следующих методов объекта класса CActiveRecord: CActiveRecord::find() CActiveRecord::findAll() CActiveRecord::findByPk() CActiveRecord::findAllByPk() CActiveRecord::findByAttributes() CActiveRecord::findAllByAttributes() CActiveRecord::count() Может быть установлено одним из следующих способов: Одна группа условий: $criteria->scopes='scopeName'; Несколько групп условий: $criteria->scopes=array( 'scopeName1', 'scopeName2'); Группа условий с параметрами: $criteria->scopes=array('scopeName'=>array($params)); Несколько групп условий с параметрами: $criteria->scopes=array( 'scopeName1'=>array($params1), 'scopeName2'=>array($params2)); Несколько групп условий с одним именем и разными параметрами: array( array('scopeName'=>array($params1)), array('scopeName'=>array($params2)) );
select	mixed	Выбираемые столбцы. Добавляется в оператор SELECT в SQL-выражении. Свойство может быть либо строкой (разделенные запятыми имена столбцов) либо массивом имен столбцов. По умолчанию - '*', т.е., выбираются все столбцы
together	boolean	Должны ли внешние таблицы быть связаны с первичной таблицей в одном SQL-запросе. Свойство используется только в Active Record-запросах для связей HAS_MANY и MANY_MANY. Если данное свойство установлено в значение true, то для реляционного AR-запроса будет выполнен лишь один SQL-запрос, даже если первичная таблица лимитирована (установлено ограничение количества записей) и связь между внешней и первичной таблицами является связью многие-к-одному. Если данное свойство установлено в значение false, для каждой связи HAS_MANY будет выполнен отдельный SQL-запрос. Если данное свойство не установлено при лимитировании первичной таблицы или использовании постраничной разбивки, то для каждой связи HAS_MANY будет выполнен отдельный SQL-запрос, иначе будет выполнен единственный SQL-запрос
with	mixed	Реляционный критерий запроса. Используется для получения связанных объектов в режиме "жадной" загрузки. Свойство имеет значение только если критерий передан в качестве параметра в один из следующих методов объекта класса CActiveRecord: CActiveRecord::find() CActiveRecord::findAll() CActiveRecord::findByPk() CActiveRecord::findAllByPk() CActiveRecord::findByAttributes() CActiveRecord::findAllByAttributes() CActiveRecord::count() Значение свойства будет использовано в качестве параметра метода CActiveRecord::with() для выполнения "жадной" загрузки. Обратитесь к описанию метода CActiveRecord::with() за подробностями настройки данного параметра

Методы CDbCriteria:

Название	Параметры	Описание
__construct($data=array())	$data начальные значения параметров критерия (индексированы по именам свойств)	Конструктор
__wakeup()		Переименовывает (remaps) параметры критерия при десериализации для предотвращения коллизий имен
addBetweenCondition($column, $valueStart, $valueEnd, $operator='AND')	$column имя столбца поиска $valueStart начальное значение диапазона $valueEnd конечное значение диапазона $operator оператор, используемый для соединения нового условия с имеющимся. По умолчанию - 'AND'	Добавляет условие between (диапазон). Новое условие диапазон и имеющееся будут соединены определенным оператором, по умолчанию - оператор 'AND'. Если одно или оба значения пусты, то условие не будет добавлено к существующему. Данный метод обрабатывает случай, при котором существующее условие пусто. После вызова данного метода, свойство condition будет изменено
addColumnCondition($columns, $columnOperator='AND', $operator='AND')	$columns список имен столбцов и сравниваемых значений (имя => значение) $columnOperator оператор для соединения нескольких столбцов в условии сравнения. По умолчанию - 'AND' $operator оператор, используемый для соединения нового условия с имеющимся. По умолчанию - 'AND'	Добавляет условие для сравнения переданного списка со значениями столбцов. Данное условие и имеющееся будут соединены определенным оператором, по умолчанию - оператор 'AND'. Условие генерируется сравнением каждого столбца соответствующему значению
addCondition($condition, $operator='AND')	$condition новое условие. Может быть либо строкой либо массивом строк $operator оператор соединения отдельных условий. По умолчанию - 'AND'	Добавляет условие к уже имеющемуся (condition). Новое условие и имеющееся будут соединены определенным оператором, по умолчанию - это оператор 'AND'. Новое условие может быть массивом. В этом случае все элементы массива будут соединены оператором. Данный метод обрабатывает случай, когда существующее условие пусто. После вызова метода, свойство condition будет изменено
addInCondition($column, $values, $operator='AND')	$column имя столбца (или допустимое SQL-выражение) $values список значений, среди которых должно быть значение столбца $operator оператор, используемый для соединения нового условия с имеющимся. По умолчанию - 'AND'	Добавляет условие IN к уже имеющемуся (condition). Условие IN и имеющееся будут соединены определенным оператором, по умолчанию - оператор 'AND'. Условие IN генерируется с использованием SQL-оператора IN, требующим, чтобы значение определенного столбца находилось в переданном списке значений
addNotInCondition($column, $values, $operator='AND')	$column имя столбца (или допустимое SQL-выражение) $values список значений, среди которых НЕ должно быть значение столбца $operator оператор, используемый для соединения нового условия с имеющимся. По умолчанию - 'AND'	Добавляет условие NOT IN к уже имеющемуся (condition). Условие NOT IN и имеющееся будут соединены определенным оператором, по умолчанию - оператор 'AND'. Условие IN генерируется с использованием SQL-оператора IN, требующим, чтобы значение определенного столбца НЕ находилось в переданном списке значений
addSearchCondition($column, $keyword, $escape=true, $operator='AND', $like='LIKE')	$column имя столбца (или допустимое SQL-выражение) $keyword слово для поиска. Эта интерпретация слов для поиска зависит от следующих параметров $escape экранировать ли слово для поиска, если оно содержит символы % или _. Если данный параметр имеет значение true (по умолчанию), специальные символы % (обозначает 0 или более символов) и _ (обозначает 1 символ) будут экранированы, а слово для поиска будет окружено символом % с обоих концов. Если данный параметр имеет значение false, слово по умолчанию будет напрямую использоваться для поиска соответствий без каких-либо изменений. $operator оператор, используемый для соединения нового условия с имеющимся. По умолчанию - 'AND' $like оператор LIKE. По умолчанию - 'LIKE'. Можно установить в значение 'NOT LIKE'	Добавляет условие поиска к уже имеющемуся (condition). Условие поиска и имеющееся будут соединены определенным оператором, по умолчанию - оператор 'AND'. Условие поиска генерируется с использованием SQL-оператора LIKE с переданным именем и словом для поиска
compare($column, $value, $partialMatch=false, $operator='AND', $escape=true)	Оператор сравнения определяется интеллектуально на основе первых нескольких символов переданного значения. В частности, распознаются следующие операторы, стоящие в начале переданного значения:<: значение столбца должно быть меньше переданного значения; >: значение столбца должно быть больше переданного значения; <=: значение столбца должно быть меньше либо равно переданному значению; >=: значение столбца должно быть больше либо равно переданному значению; <>: значение столбца не должно равняться переданному значению. Примечание: если параметр $partialMatch равен значению true, то значение не должно являться подстрокой значения столбца; =: значение столбца должно равняться переданному значению; ни один из вышеперечисленных: значение столбца должно равняться переданному значению. Примечание: если параметр $partialMatch равен значению true, то значение столбца должно быть таким же, как переданное значение или быть подстрокой переданного значения. Примечание: окружающие пробелы будут удалены из значения перед сравнением. Если значение пусто, выражение сравнения не будет добавлено к условию поиска. $column имя столбца для поиска $value значение, с которым производится сравнение. Если значение является строкой, то будет выполнено интеллектуальное сравнение. Если значение - это массив, то производится точное сравнение по каждому элементу массива. Если параметр пуст, то существующее условие поиска не будет изменено $partialMatch надо ли проверять значение на частичное совпадение (используя операторы LIKE и NOT LIKE). По умолчанию - false, т.е., проверяется точное совпадение $operator оператор, используемый для соединения нового условия с имеющимся. По умолчанию - 'AND' $escape должно ли значение экранироваться, если свойство $partialMatch установлено в значение true и значение содержит символы % или _. Если данный параметр установлен в значение true (по умолчанию), то специальные символы % (соответствует 0 или более символам) и _ (соответствует единственному символу) будут экранированы и значение будет окружено символами % с обеих сторон. Если данный параметр имеет значение false, то значение будет использовано для поиска соответствий напрямую без изменений	Добавляет выражение сравнения к свойству condition. Данный метод - это хелпер, добавляющий новое выражение сравнения к свойству condition. Действие производится сравнением столбца с переданным значением с использованием некоторого оператора сравнения.
mergeWith($criteria, $useAnd=true)	$criteria критерий, с котором производится слияние. Может быть массивом или объектом класса CDbCriteria $useAnd использовать ли оператор 'AND' для слияния условий и их опций. Если значение равно false, то будет использоваться оператор 'OR'. По умолчанию - true	Сливает критерий с другим. В основном, слияние делает результирующий критерий более ограничивающим. Например, если оба критерия имеют условия, вместе они будут слиты оператором 'AND'. Также, критерий, переданный в метод в качестве параметра, имеет преимущество в случае, когда пара опций не может быть слита (например, LIMIT, OFFSET)
toArray()		Представление критерия в виде массива

Примеры

// создаем экземпляр  класса CDbCriteria
$criteria = new CDbCriteria;
// выбираемые все столбцы из всех таблиц, участвующих в запросе
$criteria->select = '*';
//$criteria->select = array('post.id', 'post.category_id', 'post.user_id', 'post.title', 'user.name');
//$criteria->select = 'post.id, post.category_id, post.user_id, post.title, user.name';
// псевдоним(алиас) для текущей таблицы
$criteria->alias = 'post';
// выбираем только неповторяющиеся строки данных
$criteria->distinct = true;
// задаем условие запроса
$criteria->condition = 'post.is_hide = :is_hide AND post.user_id = :author_id';
// группируем
$criteria->group = 'post.category_id';
// условие для GROUP BY
$criteria->having = 'post.viwed > 100';
// задаем соединение с другой(ими) таблицами
$criteria->join = 'LEFT JOIN users as user ON user.id = post.user_id';
// максимальное количество возвращаемых записей
$criteria->limit = 20;
// смещение, с которого будут возвращаться записи
$criteria->offset = 5;
// сортировки результатов запроса
$criteria->order = 'post.date_create';
// параметры для замены в SQL выражении, для condition
$criteria->params = array(':is_hide'=>0, ':author_id'=>Yii::app()->user->id);
// внешние таблицы должны быть связаны с первичной таблицей в одном SQL-запросе
$criteria->together = true;
// получение связанных объектов в режиме "жадной" загрузки
$criteria->with = array('profile', 'comments', 'category');
// добавляем условие between (диапазон)
$criteria->addBetweenCondition('post.date_update', '09-12-2011', '09-12-2015');
// добавляем условие для сравнения переданного списка со значениями столбцов
$criteria->addColumnCondition(array('status'=>1), 'AND')
// добавляем условие IN к уже имеющемуся (condition)
$criteria->addInCondition('post.category_id', array('6', '24', '247'), 'OR');
// добавляем условие к уже имеющемуся (condition)
$criteria->addCondition("count_comments <= :count_comments");
// сливает критерий с другим
if($_POST['search_text']){
	$criteriaSearch = new CDbCriteria();
	$criteriaSearch->addSearchCondition('description', $_POST['search_text']. true, 'AND', 'LIKE');
	$criteria->mergeWith($criteriaSearch, 'AND');
}
$posts = Post::model()->findAll($criteria);

CDbCriteria в DAO

Для ускорения работы приложения можно отказаться от AR в пользу DAO. Но это накладывает некоторые ограничения, например, придется отказаться от использования together, with - они могут не попасть в результирующий запрос.

$criteria = new CDbCriteria;
$builder = new CDbCommandBuilder(Yii::app()->db->getSchema());
$command = $builder->createFindCommand('post', $criteria);
$result = $command->queryColumn();//query(), queryAll(), queryRow(), queryScalar()