Yii Framework v1.1.3 Class Reference

CDbCriteria

Package	system.db.schema
Inheritance	class CDbCriteria
Since	1.0
Version	$Id: CDbCriteria.php 2222 2010-06-24 19:00:27Z qiang.xue $

Property Details

the alias name of the table. If not set, it means the alias is 't'.

query condition. This refers to the WHERE clause in an SQL statement. For example, age>31 AND team=1.

whether to select distinct rows of data only. If this is set true, the SELECT clause would be changed to SELECT DISTINCT.

how to group the query results. This refers to the GROUP BY clause in an SQL statement. For example, 'projectID, teamID'.

the condition to be applied with GROUP-BY clause. For example, 'SUM(revenue)<50000'.

how to join with other tables. This refers to the JOIN clause in an SQL statement. For example, 'LEFT JOIN users ON users.id=authorID'.

maximum number of records to be returned. If less than 0, it means no limit.

zero-based offset from where the records are to be returned. If less than 0, it means starting from the beginning.

how to sort the query results. This refers to the ORDER BY clause in an SQL statement.

the global counter for anonymous binding parameters. This counter is used for generating the name for the anonymous parameters.

list of query parameter values indexed by parameter placeholders. For example, array(':name'=>'Dan', ':age'=>31).

the columns being selected. This refers to the SELECT clause in an SQL statement. The property can be either a string (column names separated by commas) or an array of column names. Defaults to '*', meaning all columns.

the relational query criteria. This is used for fetching related objects in eager loading fashion. This property is effective only when the criteria is passed as a parameter to the following methods of CActiveRecord:

• CActiveRecord::find()
• CActiveRecord::findAll()
• CActiveRecord::findByPk()
• CActiveRecord::findAllByPk()
• CActiveRecord::findByAttributes()
• CActiveRecord::findAllByAttributes()
• CActiveRecord::count()

The property value will be used as the parameter to the CActiveRecord::with() method to perform the eager loading. Please refer to CActiveRecord::with() on how to specify this parameter.

Method Details

public void __construct(array $data=array ( ))
$data	array	criteria initial property values (indexed by property name)

Constructor.

public CDbCriteria addBetweenCondition(string $column, string $valueStart, string $valueEnd, string $operator='AND')
$column	string	the name of the column to search between.
$valueStart	string	the beginning value to start the between search.
$valueEnd	string	the ending value to end the between search.
$operator	string	the operator used to concatenate the new condition with the existing one. Defaults to 'AND'.
{return}	CDbCriteria	the criteria object itself

Adds a between condition to the condition property.

The new between condition and the existing condition will be concatenated via the specified operator which defaults to 'AND'. If one or both values are empty then the condition is not added to the existing condition. This method handles the case when the existing condition is empty. After calling this method, the condition property will be modified.

public CDbCriteria addColumnCondition(array $columns, string $columnOperator='AND', string $operator='AND')
$columns	array	list of column names and values to be matched (name=>value)
$columnOperator	string	the operator to concatenate multiple column matching condition. Defaults to 'AND'.
$operator	string	the operator used to concatenate the new condition with the existing one. Defaults to 'AND'.
{return}	CDbCriteria	the criteria object itself

Appends a condition for matching the given list of column values. The generated condition will be concatenated to the existing condition via the specified operator which defaults to 'AND'. The condition is generated by matching each column and the corresponding value.

public CDbCriteria addCondition(mixed $condition, string $operator='AND')
$condition	mixed	the new condition. It can be either a string or an array of strings.
$operator	string	the operator to join different conditions. Defaults to 'AND'.
{return}	CDbCriteria	the criteria object itself

Appends a condition to the existing condition. The new condition and the existing condition will be concatenated via the specified operator which defaults to 'AND'. The new condition can also be an array. In this case, all elements in the array will be concatenated together via the operator. This method handles the case when the existing condition is empty. After calling this method, the condition property will be modified.

public CDbCriteria addInCondition(string $column, array $values, string $operator='AND')
$column	string	the column name (or a valid SQL expression)
$values	array	list of values that the column value should be in
$operator	string	the operator used to concatenate the new condition with the existing one. Defaults to 'AND'.
{return}	CDbCriteria	the criteria object itself

Appends an IN condition to the existing condition. The IN condition and the existing condition will be concatenated via the specified operator which defaults to 'AND'. The IN condition is generated by using the SQL IN operator which requires the specified column value to be among the given list of values.

public CDbCriteria addNotInCondition(string $column, array $values, string $operator='AND')
$column	string	the column name (or a valid SQL expression)
$values	array	list of values that the column value should be in
$operator	string	the operator used to concatenate the new condition with the existing one. Defaults to 'AND'.
{return}	CDbCriteria	the criteria object itself

Appends an NOT IN condition to the existing condition. The NOT IN condition and the existing condition will be concatenated via the specified operator which defaults to 'AND'. The NOT IN condition is generated by using the SQL NOT IN operator which requires the specified column value to be among the given list of values.

public CDbCriteria addSearchCondition(string $column, string $keyword, boolean $escape=true, string $operator='AND', string $like='LIKE')
$column	string	the column name (or a valid SQL expression)
$keyword	string	the search keyword. This interpretation of the keyword is affected by the next parameter.
$escape	boolean	whether the keyword should be escaped if it contains characters % or _. When this parameter is true (default), the special characters % (matches 0 or more characters) and _ (matches a single character) will be escaped, and the keyword will be surrounded with a % character on both ends. When this parameter is false, the keyword will be directly used for matching without any change.
$operator	string	the operator used to concatenate the new condition with the existing one. Defaults to 'AND'.
$like	string	the LIKE operator. Defaults to 'LIKE'. You may also set this to be 'NOT LIKE'.
{return}	CDbCriteria	the criteria object itself

Appends a search condition to the existing condition. The search condition and the existing condition will be concatenated via the specified operator which defaults to 'AND'. The search condition is generated using the SQL LIKE operator with the given column name and search keyword.

public CDbCriteria compare(string $column, mixed $value, boolean $partialMatch=false, string $operator='AND')
$column	string	the name of the column to be searched
$value	mixed	the column value to be compared with. If the value is a string, the aforementioned intelligent comparison will be conducted. If the value is an array, the comparison is done by exact match of any of the value in the array. If the string or the array is empty, the existing search condition will not be modified.
$partialMatch	boolean	whether the value should consider partial text match (using LIKE and NOT LIKE operators). Defaults to false, meaning exact comparison.
$operator	string	the operator used to concatenate the new condition with the existing one. Defaults to 'AND'.
{return}	CDbCriteria	the criteria object itself

Adds a comparison expression to the condition property.

This method is a helper that appends to the condition property with a new comparison expression. The comparison is done by comparing a column with the given value using some comparison operator.

The comparison operator is intelligently determined based on the first few characters in the given value. In particular, it recognizes the following operators if they appear as the leading characters in the given value:

• <: the column must be less than the given value.
• >: the column must be greater than the given value.
• <=: the column must be less than or equal to the given value.
• >=: the column must be greater than or equal to the given value.
• <>: the column must not be the same as the given value. Note that when $partialMatch is true, this would mean the value must not be a substring of the column.
• =: the column must be equal to the given value.
• none of the above: the column must be equal to the given value. Note that when $partialMatch is true, this would mean the value must be the same as the given value or be a substring of it.

Note that any surrounding white spaces will be removed from the value before comparison. When the value is empty, no comparison expression will be added to the search condition.

public void mergeWith(CDbCriteria $criteria, boolean $useAnd=true)
$criteria	CDbCriteria	the criteria to be merged with.
$useAnd	boolean	whether to use 'AND' to merge condition and having options. If false, 'OR' will be used instead. Defaults to 'AND'. This parameter has been available since version 1.0.6.

Merges with another criteria. In general, the merging makes the resulting criteria more restrictive. For example, if both criterias have conditions, they will be 'AND' together. Also, the criteria passed as the parameter takes precedence in case two options cannot be merged (e.g. LIMIT, OFFSET).

public array toArray()
{return}	array	the array representation of the criteria

Copyright © 2008-2010 by Yii Software LLC
All Rights Reserved.