CDbCriteria
| 包 | system.db.schema |
|---|---|
| 继承 | class CDbCriteria » CComponent |
| 源自 | 1.0 |
| 版本 | $Id: CDbCriteria.php 3515 2011-12-28 12:29:24Z mdomba $ |
| 源码 | framework/db/schema/CDbCriteria.php |
公共属性
隐藏继承属性
| 属性 | 类型 | 描述 | 定义在 |
|---|---|---|---|
| alias | string | the alias name of the table. | CDbCriteria |
| condition | string | query condition. | CDbCriteria |
| distinct | boolean | whether to select distinct rows of data only. | CDbCriteria |
| group | string | how to group the query results. | CDbCriteria |
| having | string | the condition to be applied with GROUP-BY clause. | CDbCriteria |
| index | string | the name of the AR attribute whose value should be used as index of the query result array. | CDbCriteria |
| join | string | how to join with other tables. | CDbCriteria |
| limit | integer | maximum number of records to be returned. | CDbCriteria |
| offset | integer | zero-based offset from where the records are to be returned. | CDbCriteria |
| order | string | how to sort the query results. | CDbCriteria |
| paramCount | integer | the global counter for anonymous binding parameters. | CDbCriteria |
| params | array | list of query parameter values indexed by parameter placeholders. | CDbCriteria |
| scopes | mixed | scopes to apply This property is effective only when passing criteria to the one of the following methods:
Can be set to one of the following:
| CDbCriteria |
| select | mixed | the columns being selected. | CDbCriteria |
| together | boolean | whether the foreign tables should be joined with the primary table in a single SQL. | CDbCriteria |
| with | mixed | the relational query criteria. | CDbCriteria |
公共方法
隐藏继承方法
| 方法 | 描述 | 定义在 |
|---|---|---|
| __call() | 如果类中没有调的方法名，则调用这个方法。 | CComponent |
| __construct() | Constructor. | CDbCriteria |
| __get() | 返回一个属性值、一个事件处理程序列表或一个行为名称。 | CComponent |
| __isset() | 检查一个属性是否为null。 | CComponent |
| __set() | 设置一个组件的属性值。 | CComponent |
| __unset() | 设置一个组件的属性为null。 | CComponent |
| __wakeup() | Remaps criteria parameters on unserialize to prevent name collisions. | CDbCriteria |
| addBetweenCondition() | Adds a between condition to the condition property. | CDbCriteria |
| addColumnCondition() | Appends a condition for matching the given list of column values. | CDbCriteria |
| addCondition() | Appends a condition to the existing condition. | CDbCriteria |
| addInCondition() | Appends an IN condition to the existing condition. | CDbCriteria |
| addNotInCondition() | Appends an NOT IN condition to the existing condition. | CDbCriteria |
| addSearchCondition() | Appends a search condition to the existing condition. | CDbCriteria |
| asa() | 返回这个名字的行为对象。 | CComponent |
| attachBehavior() | 附加一个行为到组件。 | CComponent |
| attachBehaviors() | 附加一个行为列表到组件。 | CComponent |
| attachEventHandler() | 为事件附加一个事件处理程序。 | CComponent |
| canGetProperty() | 确定属性是否可读。 | CComponent |
| canSetProperty() | 确定属性是否可写。 | CComponent |
| compare() | Adds a comparison expression to the condition property. | CDbCriteria |
| detachBehavior() | 从组件中分离一个行为。 | CComponent |
| detachBehaviors() | 从组件中分离所有行为。 | CComponent |
| detachEventHandler() | 分离一个存在的事件处理程序。 | CComponent |
| disableBehavior() | 禁用一个附加行为。 | CComponent |
| disableBehaviors() | 禁用组件附加的所有行为。 | CComponent |
| enableBehavior() | 启用一个附加行为。 | CComponent |
| enableBehaviors() | 启用组件附加的所有行为。 | CComponent |
| evaluateExpression() | 计算一个PHP表达式，或根据组件上下文执行回调。 | CComponent |
| getEventHandlers() | 返回一个事件的附加处理程序列表。 | CComponent |
| hasEvent() | 确定一个事件是否定义。 | CComponent |
| hasEventHandler() | 检查事件是否有附加的处理程序。 | CComponent |
| hasProperty() | 确定属性是否被定义。 | CComponent |
| mergeWith() | Merges with another criteria. | CDbCriteria |
| raiseEvent() | 发起一个事件。 | CComponent |
| toArray() | CDbCriteria |
属性详细
alias 属性 public string $alias;the alias name of the table. If not set, it means the alias is 't'.
condition 属性 public string $condition;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.
group 属性 public string $group;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'.
the name of the AR attribute whose value should be used as index of the query result array. Defaults to null, meaning the result array will be zero-based integers.
join 属性 public string $join;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.
offset 属性 public integer $offset;zero-based offset from where the records are to be returned. If less than 0, it means starting from the beginning.
order 属性 public string $order;how to sort the query results. This refers to the ORDER BY clause in an SQL statement.
paramCount 属性 public static integer $paramCount;the global counter for anonymous binding parameters. This counter is used for generating the name for the anonymous parameters.
params 属性 public array $params;list of query parameter values indexed by parameter placeholders. For example, array(':name'=>'Dan', ':age'=>31).
scopes to apply
This property is effective only when passing criteria to the one of the following methods:
- CActiveRecord::find()
- CActiveRecord::findAll()
- CActiveRecord::findByPk()
- CActiveRecord::findAllByPk()
- CActiveRecord::findByAttributes()
- CActiveRecord::findAllByAttributes()
- CActiveRecord::count()
Can be set to one of the following:
- One scope: $criteria->scopes='scopeName';
- Multiple scopes: $criteria->scopes=array('scopeName1','scopeName2');
- Scope with parameters: $criteria->scopes=array('scopeName'=>array($params));
- Multiple scopes with parameters: $criteria->scopes=array('scopeName1'=>array($params1),'scopeName2'=>array($params2));
- Multiple scopes with the same name: array(array('scopeName'=>array($params1)),array('scopeName'=>array($params2)));
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.
together 属性 （可用自 v1.1.4） public boolean $together;whether the foreign tables should be joined with the primary table in a single SQL. This property is only used in relational AR queries for HAS_MANY and MANY_MANY relations.
When this property is set true, only a single SQL will be executed for a relational AR query, even if the primary table is limited and the relationship between a foreign table and the primary table is many-to-one.
When this property is set false, a SQL statement will be executed for each HAS_MANY relation.
When this property is not set, if the primary table is limited or paginated, a SQL statement will be executed for each HAS_MANY relation. Otherwise, a single SQL statement will be executed for all.
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()
方法详细
__construct() 方法| public void __construct(array $data=array ( )) | ||
| $data | array | criteria initial property values (indexed by property name) |
publicfunction__construct($data=array())
{
foreach($dataas$name=>$value)
$this->$name=$value;
}Constructor.
__wakeup() 方法 （可用自 v1.1.9）| public void __wakeup() |
publicfunction__wakeup()
{
$map=array();
$params=array();
foreach($this->paramsas$name=>$value)
{
$newName=self::PARAM_PREFIX.self::$paramCount++;
$map[$name]=$newName;
$params[$newName]=$value;
}
$this->condition=strtr($this->condition,$map);
$this->params=$params;
}Remaps criteria parameters on unserialize to prevent name collisions.
addBetweenCondition() 方法 （可用自 v1.1.2）| 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 |
publicfunctionaddBetweenCondition($column,$valueStart,$valueEnd,$operator='AND')
{
if($valueStart===''||$valueEnd==='')
return$this;
$paramStart=self::PARAM_PREFIX.self::$paramCount++;
$paramEnd=self::PARAM_PREFIX.self::$paramCount++;
$this->params[$paramStart]=$valueStart;
$this->params[$paramEnd]=$valueEnd;
$condition="$columnBETWEEN$paramStartAND$paramEnd";
if($this->condition==='')
$this->condition=$condition;
else
$this->condition='('.$this->condition.')'.$operator.'('.$condition.')';
return$this;
}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 |
publicfunctionaddColumnCondition($columns,$columnOperator='AND',$operator='AND')
{
$params=array();
foreach($columnsas$name=>$value)
{
if($value===null)
$params[]=$name.'ISNULL';
else
{
$params[]=$name.'='.self::PARAM_PREFIX.self::$paramCount;
$this->params[self::PARAM_PREFIX.self::$paramCount++]=$value;
}
}
return$this->addCondition(implode("$columnOperator",$params),$operator);
}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.
addCondition() 方法| 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 |
publicfunctionaddCondition($condition,$operator='AND')
{
if(is_array($condition))
{
if($condition===array())
return$this;
$condition='('.implode(')'.$operator.'(',$condition).')';
}
if($this->condition==='')
$this->condition=$condition;
else
$this->condition='('.$this->condition.')'.$operator.'('.$condition.')';
return$this;
}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.
addInCondition() 方法| 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 |
publicfunctionaddInCondition($column,$values,$operator='AND')
{
if(($n=count($values))<1)
return$this->addCondition('0=1',$operator);//0=1isusedbecauseinMSSQLvaluealonecan'tbeusedinWHERE
if($n===1)
{
$value=reset($values);
if($value===null)
return$this->addCondition($column.'ISNULL');
$condition=$column.'='.self::PARAM_PREFIX.self::$paramCount;
$this->params[self::PARAM_PREFIX.self::$paramCount++]=$value;
}
else
{
$params=array();
foreach($valuesas$value)
{
$params[]=self::PARAM_PREFIX.self::$paramCount;
$this->params[self::PARAM_PREFIX.self::$paramCount++]=$value;
}
$condition=$column.'IN('.implode(',',$params).')';
}
return$this->addCondition($condition,$operator);
}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.
addNotInCondition() 方法 （可用自 v1.1.1）| 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 not 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 |
publicfunctionaddNotInCondition($column,$values,$operator='AND')
{
if(($n=count($values))<1)
return$this;
if($n===1)
{
$value=reset($values);
if($value===null)
return$this->addCondition($column.'ISNOTNULL');
$condition=$column.'!='.self::PARAM_PREFIX.self::$paramCount;
$this->params[self::PARAM_PREFIX.self::$paramCount++]=$value;
}
else
{
$params=array();
foreach($valuesas$value)
{
$params[]=self::PARAM_PREFIX.self::$paramCount;
$this->params[self::PARAM_PREFIX.self::$paramCount++]=$value;
}
$condition=$column.'NOTIN('.implode(',',$params).')';
}
return$this->addCondition($condition,$operator);
}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.
addSearchCondition() 方法| 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 |
publicfunctionaddSearchCondition($column,$keyword,$escape=true,$operator='AND',$like='LIKE')
{
if($keyword=='')
return$this;
if($escape)
$keyword='%'.strtr($keyword,array('%'=>'%','_'=>'_','\'=>'\\')).'%';
$condition=$column."$like".self::PARAM_PREFIX.self::$paramCount;
$this->params[self::PARAM_PREFIX.self::$paramCount++]=$keyword;
return$this->addCondition($condition,$operator);
}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.
compare() 方法 （可用自 v1.1.1）| public CDbCriteria compare(string $column, mixed $value, boolean $partialMatch=false, string $operator='AND', boolean $escape=true) | ||
| $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'. |
| $escape | boolean | whether the value should be escaped if $partialMatch is true and the value 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 value will be surrounded with a % character on both ends. When this parameter is false, the value will be directly used for matching without any change. |
| {return} | CDbCriteria | the criteria object itself |
publicfunctioncompare($column,$value,$partialMatch=false,$operator='AND',$escape=true)
{
if(is_array($value))
{
if($value===array())
return$this;
return$this->addInCondition($column,$value,$operator);
}
else
$value="$value";
if(preg_match('/^(?:s*(<>|<=|>=|<|>|=))?(.*)$/',$value,$matches))
{
$value=$matches[2];
$op=$matches[1];
}
else
$op='';
if($value==='')
return$this;
if($partialMatch)
{
if($op==='')
return$this->addSearchCondition($column,$value,$escape,$operator);
if($op==='<>')
return$this->addSearchCondition($column,$value,$escape,$operator,'NOTLIKE');
}
elseif($op==='')
$op='=';
$this->addCondition($column.$op.self::PARAM_PREFIX.self::$paramCount,$operator);
$this->params[self::PARAM_PREFIX.self::$paramCount++]=$value;
return$this;
}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.mergeWith() 方法
| public void mergeWith(mixed $criteria, boolean $useAnd=true) | ||
| $criteria | mixed | the criteria to be merged with. Either an array or CDbCriteria. |
| $useAnd | boolean | whether to use 'AND' to merge condition and having options. If false, 'OR' will be used instead. Defaults to 'AND'. |
publicfunctionmergeWith($criteria,$useAnd=true)
{
$and=$useAnd?'AND':'OR';
if(is_array($criteria))
$criteria=newself($criteria);
if($this->select!==$criteria->select)
{
if($this->select==='*')
$this->select=$criteria->select;
elseif($criteria->select!=='*')
{
$select1=is_string($this->select)?preg_split('/s*,s*/',trim($this->select),-1,PREG_SPLIT_NO_EMPTY):$this->select;
$select2=is_string($criteria->select)?preg_split('/s*,s*/',trim($criteria->select),-1,PREG_SPLIT_NO_EMPTY):$criteria->select;
$this->select=array_merge($select1,array_diff($select2,$select1));
}
}
if($this->condition!==$criteria->condition)
{
if($this->condition==='')
$this->condition=$criteria->condition;
elseif($criteria->condition!=='')
$this->condition="({$this->condition})$and({$criteria->condition})";
}
if($this->params!==$criteria->params)
$this->params=array_merge($this->params,$criteria->params);
if($criteria->limit>0)
$this->limit=$criteria->limit;
if($criteria->offset>=0)
$this->offset=$criteria->offset;
if($criteria->alias!==null)
$this->alias=$criteria->alias;
if($this->order!==$criteria->order)
{
if($this->order==='')
$this->order=$criteria->order;
elseif($criteria->order!=='')
$this->order=$criteria->order.','.$this->order;
}
if($this->group!==$criteria->group)
{
if($this->group==='')
$this->group=$criteria->group;
elseif($criteria->group!=='')
$this->group.=','.$criteria->group;
}
if($this->join!==$criteria->join)
{
if($this->join==='')
$this->join=$criteria->join;
elseif($criteria->join!=='')
$this->join.=''.$criteria->join;
}
if($this->having!==$criteria->having)
{
if($this->having==='')
$this->having=$criteria->having;
elseif($criteria->having!=='')
$this->having="({$this->having})$and({$criteria->having})";
}
if($criteria->distinct>0)
$this->distinct=$criteria->distinct;
if($criteria->together!==null)
$this->together=$criteria->together;
if($criteria->index!==null)
$this->index=$criteria->index;
if(empty($this->scopes))
$this->scopes=$criteria->scopes;
elseif(!empty($criteria->scopes))
{
$scopes1=(array)$this->scopes;
$scopes2=(array)$criteria->scopes;
foreach($scopes1as$k=>$v)
{
if(is_integer($k))
$scopes[]=$v;
elseif(isset($scopes2[$k]))
$scopes[]=array($k=>$v);
else
$scopes[$k]=$v;
}
foreach($scopes2as$k=>$v)
{
if(is_integer($k))
$scopes[]=$v;
elseif(isset($scopes1[$k]))
$scopes[]=array($k=>$v);
else
$scopes[$k]=$v;
}
$this->scopes=$scopes;
}
if(empty($this->with))
$this->with=$criteria->with;
elseif(!empty($criteria->with))
{
$this->with=(array)$this->with;
foreach((array)$criteria->withas$k=>$v)
{
if(is_integer($k))
$this->with[]=$v;
elseif(isset($this->with[$k]))
{
$excludes=array();
foreach(array('joinType','on')as$opt)
{
if(isset($this->with[$k][$opt]))
$excludes[$opt]=$this->with[$k][$opt];
if(isset($v[$opt]))
$excludes[$opt]=($opt==='on'&&isset($excludes[$opt])&&$v[$opt]!==$excludes[$opt])?
"($excludes[$opt])AND$v[$opt]":$v[$opt];
unset($this->with[$k][$opt]);
unset($v[$opt]);
}
$this->with[$k]=newself($this->with[$k]);
$this->with[$k]->mergeWith($v,$useAnd);
$this->with[$k]=$this->with[$k]->toArray();
if(count($excludes)!==0)
$this->with[$k]=CMap::mergeArray($this->with[$k],$excludes);
}
else
$this->with[$k]=$v;
}
}
}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).
toArray() 方法| public array toArray() | ||
| {return} | array | the array representation of the criteria |
publicfunctiontoArray()
{
$result=array();
foreach(array('select','condition','params','limit','offset','order','group','join','having','distinct','scopes','with','alias','index','together')as$name)
$result[$name]=$this->$name;
return$result;
}