===== Примеры использования CDbCriteria в Yii =====

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

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

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

<code php>
$criteria=new CDbCriteria();

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

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

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

</code>

==== Свойства 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** ()| |Представление критерия в виде массива|

\\

====Примеры====
<code php>
// создаем экземпляр  класса 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);
</code>
====CDbCriteria в DAO====
Для ускорения работы приложения можно отказаться от AR в пользу DAO. Но это накладывает некоторые ограничения, например, придется отказаться от использования together, with - они могут не попасть в результирующий запрос.

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