CActiveRecord
Package | system.db.ar |
---|---|
Inheritance | abstract class CActiveRecord » CModel » CComponent |
Implements | ArrayAccess, Traversable, IteratorAggregate |
Since | 1.0 |
Source Code | framework/db/ar/CActiveRecord.php |
It implements the active record design pattern, a popular Object-Relational Mapping (ORM) technique. Please check the Guide for more details about this class.
Public Properties
Property | Type | Description | Defined By |
---|---|---|---|
attributes | array | Returns all column attribute values. | CActiveRecord |
commandBuilder | CDbCommandBuilder | Returns the command builder used by this AR. | CActiveRecord |
db | CDbConnection | the default database connection for all active record classes. | CActiveRecord |
dbConnection | CDbConnection | Returns the database connection used by active record. | CActiveRecord |
dbCriteria | CDbCriteria | Returns the query criteria associated with this model. | CActiveRecord |
errors | array | Returns the errors for all attribute or a single attribute. | CModel |
isNewRecord | boolean | Returns if the current record is new (was never saved to database) | CActiveRecord |
iterator | CMapIterator | Returns an iterator for traversing the attributes in the model. | CModel |
metaData | CActiveRecordMetaData | Returns the meta-data for this AR | CActiveRecord |
oldPrimaryKey | mixed | Returns the old primary key value. | CActiveRecord |
primaryKey | mixed | Returns the primary key value. | CActiveRecord |
safeAttributeNames | array | Returns the attribute names that are safe to be massively assigned. | CModel |
scenario | string | Returns the scenario that this model is used in. | CModel |
tableAlias | string | Returns the table alias to be used by the find methods. | CActiveRecord |
tableSchema | CDbTableSchema | Returns the metadata of the table that this AR belongs to | CActiveRecord |
validatorList | CList | Returns all the validators declared in the model. | CModel |
validators | array | Returns the validators applicable to the current scenario. | CModel |
Public Methods
Method | Description | Defined By |
---|---|---|
__call() | Calls the named method which is not a class method. | CActiveRecord |
__construct() | Constructor. | CActiveRecord |
__get() | PHP getter magic method. | CActiveRecord |
__isset() | Checks if a property value is null. | CActiveRecord |
__set() | PHP setter magic method. | CActiveRecord |
__sleep() | PHP sleep magic method. | CActiveRecord |
__unset() | Sets a component property to be null. | CActiveRecord |
addError() | Adds a new error to the specified attribute. | CModel |
addErrors() | Adds a list of errors. | CModel |
addRelatedRecord() | Do not call this method. This method is used internally by CActiveFinder to populate | CActiveRecord |
afterFindInternal() | Calls afterFind. | CActiveRecord |
applyScopes() | Applies the query scopes to the given criteria. | CActiveRecord |
asa() | Returns the named behavior object. | CComponent |
attachBehavior() | Attaches a behavior to this component. | CComponent |
attachBehaviors() | Attaches a list of behaviors to the component. | CComponent |
attachEventHandler() | Attaches an event handler to an event. | CComponent |
attributeLabels() | Returns the attribute labels. | CModel |
attributeNames() | Returns the list of all attribute names of the model. | CActiveRecord |
beforeFindInternal() | Calls beforeFind. | CActiveRecord |
behaviors() | Returns a list of behaviors that this model should behave as. | CModel |
cache() | Sets the parameters about query caching. | CActiveRecord |
canGetProperty() | Determines whether a property can be read. | CComponent |
canSetProperty() | Determines whether a property can be set. | CComponent |
clearErrors() | Removes errors for all attributes or a single attribute. | CModel |
count() | Finds the number of rows satisfying the specified query condition. | CActiveRecord |
countByAttributes() | Finds the number of rows that have the specified attribute values. | CActiveRecord |
countBySql() | Finds the number of rows using the given SQL statement. | CActiveRecord |
createValidators() | Creates validator objects based on the specification in rules. | CModel |
defaultScope() | Returns the default named scope that should be implicitly applied to all queries for this model. | CActiveRecord |
delete() | Deletes the row corresponding to this active record. | CActiveRecord |
deleteAll() | Deletes rows with the specified condition. | CActiveRecord |
deleteAllByAttributes() | Deletes rows which match the specified attribute values. | CActiveRecord |
deleteByPk() | Deletes rows with the specified primary key. | CActiveRecord |
detachBehavior() | Detaches a behavior from the component. | CComponent |
detachBehaviors() | Detaches all behaviors from the component. | CComponent |
detachEventHandler() | Detaches an existing event handler. | CComponent |
disableBehavior() | Disables an attached behavior. | CComponent |
disableBehaviors() | Disables all behaviors attached to this component. | CComponent |
enableBehavior() | Enables an attached behavior. | CComponent |
enableBehaviors() | Enables all behaviors attached to this component. | CComponent |
equals() | Compares current active record with another one. | CActiveRecord |
evaluateExpression() | Evaluates a PHP expression or callback under the context of this component. | CComponent |
exists() | Checks whether there is row satisfying the specified condition. | CActiveRecord |
find() | Finds a single active record with the specified condition. | CActiveRecord |
findAll() | Finds all active records satisfying the specified condition. | CActiveRecord |
findAllByAttributes() | Finds all active records that have the specified attribute values. | CActiveRecord |
findAllByPk() | Finds all active records with the specified primary keys. | CActiveRecord |
findAllBySql() | Finds all active records using the specified SQL statement. | CActiveRecord |
findByAttributes() | Finds a single active record that has the specified attribute values. | CActiveRecord |
findByPk() | Finds a single active record with the specified primary key. | CActiveRecord |
findBySql() | Finds a single active record with the specified SQL statement. | CActiveRecord |
generateAttributeLabel() | Generates a user friendly attribute label. | CModel |
getActiveFinder() | Given 'with' options returns a new active finder instance. | CActiveRecord |
getActiveRelation() | Returns the named relation declared for this AR class. | CActiveRecord |
getAttribute() | Returns the named attribute value. | CActiveRecord |
getAttributeLabel() | Returns the text label for the specified attribute. | CActiveRecord |
getAttributes() | Returns all column attribute values. | CActiveRecord |
getCommandBuilder() | Returns the command builder used by this AR. | CActiveRecord |
getDbConnection() | Returns the database connection used by active record. | CActiveRecord |
getDbCriteria() | Returns the query criteria associated with this model. | CActiveRecord |
getError() | Returns the first error of the specified attribute. | CModel |
getErrors() | Returns the errors for all attribute or a single attribute. | CModel |
getEventHandlers() | Returns the list of attached event handlers for an event. | CComponent |
getIsNewRecord() | Returns if the current record is new (was never saved to database) | CActiveRecord |
getIterator() | Returns an iterator for traversing the attributes in the model. | CModel |
getMetaData() | Returns the meta-data for this AR | CActiveRecord |
getOldPrimaryKey() | Returns the old primary key value. | CActiveRecord |
getPrimaryKey() | Returns the primary key value. | CActiveRecord |
getRelated() | Returns the related record(s). | CActiveRecord |
getSafeAttributeNames() | Returns the attribute names that are safe to be massively assigned. | CModel |
getScenario() | Returns the scenario that this model is used in. | CModel |
getTableAlias() | Returns the table alias to be used by the find methods. | CActiveRecord |
getTableSchema() | Returns the metadata of the table that this AR belongs to | CActiveRecord |
getValidatorList() | Returns all the validators declared in the model. | CModel |
getValidators() | Returns the validators applicable to the current scenario. | CModel |
hasAttribute() | Checks whether this AR has the named attribute | CActiveRecord |
hasErrors() | Returns a value indicating whether there is any validation error. | CModel |
hasEvent() | Determines whether an event is defined. | CComponent |
hasEventHandler() | Checks whether the named event has attached handlers. | CComponent |
hasProperty() | Determines whether a property is defined. | CComponent |
hasRelated() | Returns a value indicating whether the named related object(s) has been loaded. | CActiveRecord |
init() | Initializes this model. | CActiveRecord |
insert() | Inserts a row into the table based on this active record attributes. | CActiveRecord |
isAttributeRequired() | Returns a value indicating whether the attribute is required. | CModel |
isAttributeSafe() | Returns a value indicating whether the attribute is safe for massive assignments. | CModel |
model() | Returns the static model of the specified AR class. | CActiveRecord |
offsetExists() | Returns whether there is an element at the specified offset. | CActiveRecord |
offsetGet() | Returns the element at the specified offset. | CModel |
offsetSet() | Sets the element at the specified offset. | CModel |
offsetUnset() | Unsets the element at the specified offset. | CModel |
onAfterConstruct() | This event is raised after the model instance is created by new operator. | CModel |
onAfterDelete() | This event is raised after the record is deleted. | CActiveRecord |
onAfterFind() | This event is raised after the record is instantiated by a find method. | CActiveRecord |
onAfterSave() | This event is raised after the record is saved. | CActiveRecord |
onAfterValidate() | This event is raised after the validation is performed. | CModel |
onBeforeCount() | This event is raised before an AR finder performs a count call. | CActiveRecord |
onBeforeDelete() | This event is raised before the record is deleted. | CActiveRecord |
onBeforeFind() | This event is raised before an AR finder performs a find call. | CActiveRecord |
onBeforeSave() | This event is raised before the record is saved. | CActiveRecord |
onBeforeValidate() | This event is raised before the validation is performed. | CModel |
onUnsafeAttribute() | This method is invoked when an unsafe attribute is being massively assigned. | CModel |
populateRecord() | Creates an active record with the given attributes. | CActiveRecord |
populateRecords() | Creates a list of active records based on the input data. | CActiveRecord |
primaryKey() | Returns the primary key of the associated database table. | CActiveRecord |
raiseEvent() | Raises an event. | CComponent |
refresh() | Repopulates this active record with the latest data. | CActiveRecord |
refreshMetaData() | Refreshes the meta data for this AR class. | CActiveRecord |
relations() | This method should be overridden to declare related objects. | CActiveRecord |
resetScope() | Resets all scopes and criterias applied. | CActiveRecord |
rules() | Returns the validation rules for attributes. | CModel |
save() | Saves the current record. | CActiveRecord |
saveAttributes() | Saves a selected list of attributes. | CActiveRecord |
saveCounters() | Saves one or several counter columns for the current AR object. | CActiveRecord |
scopes() | Returns the declaration of named scopes. | CActiveRecord |
setAttribute() | Sets the named attribute value. | CActiveRecord |
setAttributes() | Sets the attribute values in a massive way. | CModel |
setDbCriteria() | Sets the query criteria for the current model. | CActiveRecord |
setIsNewRecord() | Sets if the record is new. | CActiveRecord |
setOldPrimaryKey() | Sets the old primary key value. | CActiveRecord |
setPrimaryKey() | Sets the primary key value. | CActiveRecord |
setScenario() | Sets the scenario for the model. | CModel |
setTableAlias() | Sets the table alias to be used in queries. | CActiveRecord |
tableName() | Returns the name of the associated database table. | CActiveRecord |
together() | Sets CDbCriteria::together property to be true. | CActiveRecord |
unsetAttributes() | Sets the attributes to be null. | CModel |
update() | Updates the row represented by this active record. | CActiveRecord |
updateAll() | Updates records with the specified condition. | CActiveRecord |
updateByPk() | Updates records with the specified primary key(s). | CActiveRecord |
updateCounters() | Updates one or several counter columns. | CActiveRecord |
validate() | Performs the validation. | CModel |
with() | Specifies which related objects should be eagerly loaded. | CActiveRecord |
Protected Methods
Method | Description | Defined By |
---|---|---|
afterConstruct() | This method is invoked after a model instance is created by new operator. | CModel |
afterDelete() | This method is invoked after deleting a record. | CActiveRecord |
afterFind() | This method is invoked after each record is instantiated by a find method. | CActiveRecord |
afterSave() | This method is invoked after saving a record successfully. | CActiveRecord |
afterValidate() | This method is invoked after validation ends. | CModel |
beforeCount() | This method is invoked before an AR finder executes a count call. | CActiveRecord |
beforeDelete() | This method is invoked before deleting a record. | CActiveRecord |
beforeFind() | This method is invoked before an AR finder executes a find call. | CActiveRecord |
beforeSave() | This method is invoked before saving a record (after validation, if any). | CActiveRecord |
beforeValidate() | This method is invoked before validation starts. | CModel |
instantiate() | Creates an active record instance. | CActiveRecord |
query() | Performs the actual DB query and populates the AR objects with the query result. | CActiveRecord |
Events
Event | Description | Defined By |
---|---|---|
onBeforeSave | This event is raised before the record is saved. | CActiveRecord |
onAfterSave | This event is raised after the record is saved. | CActiveRecord |
onBeforeDelete | This event is raised before the record is deleted. | CActiveRecord |
onAfterDelete | This event is raised after the record is deleted. | CActiveRecord |
onBeforeFind | This event is raised before an AR finder performs a find call. | CActiveRecord |
onAfterFind | This event is raised after the record is instantiated by a find method. | CActiveRecord |
onBeforeCount | This event is raised before an AR finder performs a count call. | CActiveRecord |
onAfterConstruct | This event is raised after the model instance is created by new operator. | CModel |
onBeforeValidate | This event is raised before the validation is performed. | CModel |
onAfterValidate | This event is raised after the validation is performed. | CModel |
onUnsafeAttribute | This method is invoked when an unsafe attribute is being massively assigned. | CModel |
Property Details
attributes property
public array getAttributes(mixed $names=true)
public void setAttributes(array $values, boolean $safeOnly=true)
Returns all column attribute values. Note, related objects are not returned.
commandBuilder property read-only
public CDbCommandBuilder getCommandBuilder()
Returns the command builder used by this AR.
db property
public static CDbConnection $db;
the default database connection for all active record classes. By default, this is the 'db' application component.
See Also
dbConnection property read-only
public CDbConnection getDbConnection()
Returns the database connection used by active record. By default, the "db" application component is used as the database connection. You may override this method if you want to use a different database connection.
dbCriteria property
public CDbCriteria getDbCriteria(boolean $createIfNull=true)
public void setDbCriteria(CDbCriteria $criteria)
Returns the query criteria associated with this model.
isNewRecord property
public boolean getIsNewRecord()
public void setIsNewRecord(boolean $value)
Returns if the current record is new (was never saved to database)
metaData property read-only
public CActiveRecordMetaData getMetaData()
Returns the meta-data for this AR
oldPrimaryKey property (available since v1.1.0)
public mixed getOldPrimaryKey()
public void setOldPrimaryKey(mixed $value)
Returns the old primary key value. This refers to the primary key value that is populated into the record after executing a find method (e.g. find(), findAll()). The value remains unchanged even if the primary key attribute is manually assigned with a different value.
primaryKey property
public mixed getPrimaryKey()
public void setPrimaryKey(mixed $value)
Returns the primary key value.
tableAlias property (available since v1.1.1)
public string getTableAlias(boolean $quote=false, boolean $checkScopes=true)
public void setTableAlias(string $alias)
Returns the table alias to be used by the find methods. In relational queries, the returned table alias may vary according to the corresponding relation declaration. Also, the default table alias set by setTableAlias may be overridden by the applied scopes.
tableSchema property read-only
public CDbTableSchema getTableSchema()
Returns the metadata of the table that this AR belongs to
Method Details
__call() method
public mixed __call(string $name, array $parameters) | ||
$name | string | the method name |
$parameters | array | method parameters |
{return} | mixed | the method return value |
public function __call($name,$parameters)
{
if(isset($this->getMetaData()->relations[$name]))
{
if(empty($parameters))
return $this->getRelated($name,false);
else
return $this->getRelated($name,false,$parameters[0]);
}
$scopes=$this->scopes();
if(isset($scopes[$name]))
{
$this->getDbCriteria()->mergeWith($scopes[$name]);
return $this;
}
return parent::__call($name,$parameters);
}
Calls the named method which is not a class method. Do not call this method. This is a PHP magic method that we override to implement the named scope feature.
__construct() method
public void __construct(string $scenario='insert') | ||
$scenario | string | scenario name. See CModel::scenario for more details about this parameter. Note: in order to setup initial model parameters use init() or afterConstruct(). Do NOT override the constructor unless it is absolutely necessary! |
public function __construct($scenario='insert')
{
if($scenario===null) // internally used by populateRecord() and model()
return;
$this->setScenario($scenario);
$this->setIsNewRecord(true);
$this->_attributes=$this->getMetaData()->attributeDefaults;
$this->init();
$this->attachBehaviors($this->behaviors());
$this->afterConstruct();
}
Constructor.
__get() method
public mixed __get(string $name) | ||
$name | string | property name |
{return} | mixed | property value |
public function __get($name)
{
if(isset($this->_attributes[$name]))
return $this->_attributes[$name];
elseif(isset($this->getMetaData()->columns[$name]))
return null;
elseif(isset($this->_related[$name]))
return $this->_related[$name];
elseif(isset($this->getMetaData()->relations[$name]))
return $this->getRelated($name);
else
return parent::__get($name);
}
PHP getter magic method. This method is overridden so that AR attributes can be accessed like properties.
See Also
__isset() method
public boolean __isset(string $name) | ||
$name | string | the property name or the event name |
{return} | boolean | whether the property value is null |
public function __isset($name)
{
if(isset($this->_attributes[$name]))
return true;
elseif(isset($this->getMetaData()->columns[$name]))
return false;
elseif(isset($this->_related[$name]))
return true;
elseif(isset($this->getMetaData()->relations[$name]))
return $this->getRelated($name)!==null;
else
return parent::__isset($name);
}
Checks if a property value is null. This method overrides the parent implementation by checking if the named attribute is null or not.
__set() method
public void __set(string $name, mixed $value) | ||
$name | string | property name |
$value | mixed | property value |
public function __set($name,$value)
{
if($this->setAttribute($name,$value)===false)
{
if(isset($this->getMetaData()->relations[$name]))
$this->_related[$name]=$value;
else
parent::__set($name,$value);
}
}
PHP setter magic method. This method is overridden so that AR attributes can be accessed like properties.
__sleep() method
public array __sleep() | ||
{return} | array |
public function __sleep()
{
return array_keys((array)$this);
}
PHP sleep magic method. This method ensures that the model meta data reference is set to null.
__unset() method
public void __unset(string $name) | ||
$name | string | the property name or the event name |
public function __unset($name)
{
if(isset($this->getMetaData()->columns[$name]))
unset($this->_attributes[$name]);
elseif(isset($this->getMetaData()->relations[$name]))
unset($this->_related[$name]);
else
parent::__unset($name);
}
Sets a component property to be null. This method overrides the parent implementation by clearing the specified attribute value.
addRelatedRecord() method
public void addRelatedRecord(string $name, mixed $record, mixed $index) | ||
$name | string | attribute name |
$record | mixed | the related record |
$index | mixed | the index value in the related object collection. If true, it means using zero-based integer index. If false, it means a HAS_ONE or BELONGS_TO object and no index is needed. |
public function addRelatedRecord($name,$record,$index)
{
if($index!==false)
{
if(!isset($this->_related[$name]))
$this->_related[$name]=array();
if($record instanceof CActiveRecord)
{
if($index===true)
$this->_related[$name][]=$record;
else
$this->_related[$name][$index]=$record;
}
}
elseif(!isset($this->_related[$name]))
$this->_related[$name]=$record;
}
Do not call this method. This method is used internally by CActiveFinder to populate related objects. This method adds a related object to this record.
afterDelete() method
protected void afterDelete() |
protected function afterDelete()
{
if($this->hasEventHandler('onAfterDelete'))
$this->onAfterDelete(new CEvent($this));
}
This method is invoked after deleting a record. The default implementation raises the onAfterDelete event. You may override this method to do postprocessing after the record is deleted. Make sure you call the parent implementation so that the event is raised properly.
afterFind() method
protected void afterFind() |
protected function afterFind()
{
if($this->hasEventHandler('onAfterFind'))
$this->onAfterFind(new CEvent($this));
}
This method is invoked after each record is instantiated by a find method. The default implementation raises the onAfterFind event. You may override this method to do postprocessing after each newly found record is instantiated. Make sure you call the parent implementation so that the event is raised properly.
afterFindInternal() method
public void afterFindInternal() |
public function afterFindInternal()
{
$this->afterFind();
}
Calls afterFind. This method is internally used.
afterSave() method
protected void afterSave() |
protected function afterSave()
{
if($this->hasEventHandler('onAfterSave'))
$this->onAfterSave(new CEvent($this));
}
This method is invoked after saving a record successfully. The default implementation raises the onAfterSave event. You may override this method to do postprocessing after record saving. Make sure you call the parent implementation so that the event is raised properly.
applyScopes() method
public void applyScopes(CDbCriteria &$criteria) | ||
$criteria | CDbCriteria | the query criteria. This parameter may be modified by merging dbCriteria. |
public function applyScopes(&$criteria)
{
if(!empty($criteria->scopes))
{
$scs=$this->scopes();
$c=$this->getDbCriteria();
foreach((array)$criteria->scopes as $k=>$v)
{
if(is_integer($k))
{
if(is_string($v))
{
if(isset($scs[$v]))
{
$c->mergeWith($scs[$v],true);
continue;
}
$scope=$v;
$params=array();
}
elseif(is_array($v))
{
$scope=key($v);
$params=current($v);
}
}
elseif(is_string($k))
{
$scope=$k;
$params=$v;
}
call_user_func_array(array($this,$scope),(array)$params);
}
}
if(isset($c) || ($c=$this->getDbCriteria(false))!==null)
{
$c->mergeWith($criteria);
$criteria=$c;
$this->resetScope(false);
}
}
Applies the query scopes to the given criteria. This method merges dbCriteria with the given criteria parameter. It then resets dbCriteria to be null.
attributeNames() method
public array attributeNames() | ||
{return} | array | list of attribute names. |
public function attributeNames()
{
return array_keys($this->getMetaData()->columns);
}
Returns the list of all attribute names of the model. This would return all column names of the table associated with this AR class.
beforeCount() method (available since v1.1.14)
protected void beforeCount() |
protected function beforeCount()
{
if($this->hasEventHandler('onBeforeCount'))
$this->onBeforeCount(new CEvent($this));
}
This method is invoked before an AR finder executes a count call. The count calls include count and countByAttributes The default implementation raises the onBeforeCount event. If you override this method, make sure you call the parent implementation so that the event is raised properly.
beforeDelete() method
protected boolean beforeDelete() | ||
{return} | boolean | whether the record should be deleted. Defaults to true. |
protected function beforeDelete()
{
if($this->hasEventHandler('onBeforeDelete'))
{
$event=new CModelEvent($this);
$this->onBeforeDelete($event);
return $event->isValid;
}
else
return true;
}
This method is invoked before deleting a record. The default implementation raises the onBeforeDelete event. You may override this method to do any preparation work for record deletion. Make sure you call the parent implementation so that the event is raised properly.
beforeFind() method
protected void beforeFind() |
protected function beforeFind()
{
if($this->hasEventHandler('onBeforeFind'))
{
$event=new CModelEvent($this);
$this->onBeforeFind($event);
}
}
This method is invoked before an AR finder executes a find call. The find calls include find, findAll, findByPk, findAllByPk, findByAttributes, findAllByAttributes, findBySql and findAllBySql. The default implementation raises the onBeforeFind event. If you override this method, make sure you call the parent implementation so that the event is raised properly. For details on modifying query criteria see onBeforeFind event.
beforeFindInternal() method
public void beforeFindInternal() |
public function beforeFindInternal()
{
$this->beforeFind();
}
Calls beforeFind. This method is internally used.
beforeSave() method
protected boolean beforeSave() | ||
{return} | boolean | whether the saving should be executed. Defaults to true. |
protected function beforeSave()
{
if($this->hasEventHandler('onBeforeSave'))
{
$event=new CModelEvent($this);
$this->onBeforeSave($event);
return $event->isValid;
}
else
return true;
}
This method is invoked before saving a record (after validation, if any). The default implementation raises the onBeforeSave event. You may override this method to do any preparation work for record saving. Use isNewRecord to determine whether the saving is for inserting or updating record. Make sure you call the parent implementation so that the event is raised properly.
cache() method (available since v1.1.7)
public static cache(integer $duration, CCacheDependency|ICacheDependency $dependency=NULL, integer $queryCount=1) | ||
$duration | integer | the number of seconds that query results may remain valid in cache. If this is 0, the caching will be disabled. |
$dependency | CCacheDependency|ICacheDependency | the dependency that will be used when saving the query results into cache. |
$queryCount | integer | number of SQL queries that need to be cached after calling this method. Defaults to 1, meaning that the next SQL query will be cached. |
{return} | static | the active record instance itself. |
public function cache($duration, $dependency=null, $queryCount=1)
{
$this->getDbConnection()->cache($duration, $dependency, $queryCount);
return $this;
}
Sets the parameters about query caching. This is a shortcut method to CDbConnection::cache(). It changes the query caching parameter of the dbConnection instance.
count() method
public string count(mixed $condition='', array $params=array ( )) | ||
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | string | the number of rows satisfying the specified query condition. Note: type is string to keep max. precision. |
public function count($condition='',$params=array())
{
Yii::trace(get_class($this).'.count()','system.db.ar.CActiveRecord');
$this->beforeCount();
$builder=$this->getCommandBuilder();
$criteria=$builder->createCriteria($condition,$params);
$this->applyScopes($criteria);
if(empty($criteria->with))
return $builder->createCountCommand($this->getTableSchema(),$criteria)->queryScalar();
else
{
$finder=$this->getActiveFinder($criteria->with);
return $finder->count($criteria);
}
}
Finds the number of rows satisfying the specified query condition. See find() for detailed explanation about $condition and $params.
countByAttributes() method (available since v1.1.4)
public string countByAttributes(array $attributes, mixed $condition='', array $params=array ( )) | ||
$attributes | array | list of attribute values (indexed by attribute names) that the active records should match. An attribute value can be an array which will be used to generate an IN condition. |
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | string | the number of rows satisfying the specified query condition. Note: type is string to keep max. precision. |
public function countByAttributes($attributes,$condition='',$params=array())
{
Yii::trace(get_class($this).'.countByAttributes()','system.db.ar.CActiveRecord');
$prefix=$this->getTableAlias(true).'.';
$builder=$this->getCommandBuilder();
$this->beforeCount();
$criteria=$builder->createColumnCriteria($this->getTableSchema(),$attributes,$condition,$params,$prefix);
$this->applyScopes($criteria);
if(empty($criteria->with))
return $builder->createCountCommand($this->getTableSchema(),$criteria)->queryScalar();
else
{
$finder=$this->getActiveFinder($criteria->with);
return $finder->count($criteria);
}
}
Finds the number of rows that have the specified attribute values. See find() for detailed explanation about $condition and $params.
countBySql() method
public string countBySql(string $sql, array $params=array ( )) | ||
$sql | string | the SQL statement |
$params | array | parameters to be bound to the SQL statement |
{return} | string | the number of rows using the given SQL statement. Note: type is string to keep max. precision. |
public function countBySql($sql,$params=array())
{
Yii::trace(get_class($this).'.countBySql()','system.db.ar.CActiveRecord');
$this->beforeCount();
return $this->getCommandBuilder()->createSqlCommand($sql,$params)->queryScalar();
}
Finds the number of rows using the given SQL statement. This is equivalent to calling CDbCommand::queryScalar with the specified SQL statement and the parameters.
defaultScope() method
public array defaultScope() | ||
{return} | array | the query criteria. This will be used as the parameter to the constructor of CDbCriteria. |
public function defaultScope()
{
return array();
}
Returns the default named scope that should be implicitly applied to all queries for this model. Note, default scope only applies to SELECT queries. It is ignored for INSERT, UPDATE and DELETE queries. The default implementation simply returns an empty array. You may override this method if the model needs to be queried with some default criteria (e.g. only active records should be returned).
delete() method
public boolean delete() | ||
{return} | boolean | whether the deletion is successful. |
public function delete()
{
if(!$this->getIsNewRecord())
{
Yii::trace(get_class($this).'.delete()','system.db.ar.CActiveRecord');
if($this->beforeDelete())
{
$result=$this->deleteByPk($this->getPrimaryKey())>0;
$this->afterDelete();
return $result;
}
else
return false;
}
else
throw new CDbException(Yii::t('yii','The active record cannot be deleted because it is new.'));
}
Deletes the row corresponding to this active record.
deleteAll() method
public integer deleteAll(mixed $condition='', array $params=array ( )) | ||
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | integer | the number of rows deleted |
public function deleteAll($condition='',$params=array())
{
Yii::trace(get_class($this).'.deleteAll()','system.db.ar.CActiveRecord');
$builder=$this->getCommandBuilder();
$criteria=$builder->createCriteria($condition,$params);
$command=$builder->createDeleteCommand($this->getTableSchema(),$criteria);
return $command->execute();
}
Deletes rows with the specified condition. See find() for detailed explanation about $condition and $params.
deleteAllByAttributes() method
public integer deleteAllByAttributes(array $attributes, mixed $condition='', array $params=array ( )) | ||
$attributes | array | list of attribute values (indexed by attribute names) that the active records should match. An attribute value can be an array which will be used to generate an IN condition. |
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | integer | number of rows affected by the execution. |
public function deleteAllByAttributes($attributes,$condition='',$params=array())
{
Yii::trace(get_class($this).'.deleteAllByAttributes()','system.db.ar.CActiveRecord');
$builder=$this->getCommandBuilder();
$table=$this->getTableSchema();
$criteria=$builder->createColumnCriteria($table,$attributes,$condition,$params);
$command=$builder->createDeleteCommand($table,$criteria);
return $command->execute();
}
Deletes rows which match the specified attribute values. See find() for detailed explanation about $condition and $params.
deleteByPk() method
public integer deleteByPk(mixed $pk, mixed $condition='', array $params=array ( )) | ||
$pk | mixed | primary key value(s). Use array for multiple primary keys. For composite key, each key value must be an array (column name=>column value). |
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | integer | the number of rows deleted |
public function deleteByPk($pk,$condition='',$params=array())
{
Yii::trace(get_class($this).'.deleteByPk()','system.db.ar.CActiveRecord');
$builder=$this->getCommandBuilder();
$criteria=$builder->createPkCriteria($this->getTableSchema(),$pk,$condition,$params);
$command=$builder->createDeleteCommand($this->getTableSchema(),$criteria);
return $command->execute();
}
Deletes rows with the specified primary key. See find() for detailed explanation about $condition and $params.
equals() method
public boolean equals(CActiveRecord $record) | ||
$record | CActiveRecord | record to compare to |
{return} | boolean | whether the two active records refer to the same row in the database table. |
public function equals($record)
{
return $this->tableName()===$record->tableName() && $this->getPrimaryKey()===$record->getPrimaryKey();
}
Compares current active record with another one. The comparison is made by comparing table name and the primary key values of the two active records.
exists() method
public boolean exists(mixed $condition='', array $params=array ( )) | ||
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | boolean | whether there is row satisfying the specified condition. |
public function exists($condition='',$params=array())
{
Yii::trace(get_class($this).'.exists()','system.db.ar.CActiveRecord');
$builder=$this->getCommandBuilder();
$criteria=$builder->createCriteria($condition,$params);
$table=$this->getTableSchema();
$criteria->select='1';
$criteria->limit=1;
$this->applyScopes($criteria);
if(empty($criteria->with))
return $builder->createFindCommand($table,$criteria,$this->getTableAlias(false, false))->queryRow()!==false;
else
{
$criteria->select='*';
$finder=$this->getActiveFinder($criteria->with);
return $finder->count($criteria)>0;
}
}
Checks whether there is row satisfying the specified condition. See find() for detailed explanation about $condition and $params.
find() method
public static find(mixed $condition='', array $params=array ( )) | ||
$condition | mixed | query condition or criteria. If a string, it is treated as query condition (the WHERE clause); If an array, it is treated as the initial values for constructing a CDbCriteria object; Otherwise, it should be an instance of CDbCriteria. |
$params | array | parameters to be bound to an SQL statement. This is only used when the first parameter is a string (query condition). In other cases, please use CDbCriteria::params to set parameters. |
{return} | static | the record found. Null if no record is found. |
public function find($condition='',$params=array())
{
Yii::trace(get_class($this).'.find()','system.db.ar.CActiveRecord');
$criteria=$this->getCommandBuilder()->createCriteria($condition,$params);
return $this->query($criteria);
}
Finds a single active record with the specified condition.
findAll() method
public static[] findAll(mixed $condition='', array $params=array ( )) | ||
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | static[] | list of active records satisfying the specified condition. An empty array is returned if none is found. |
public function findAll($condition='',$params=array())
{
Yii::trace(get_class($this).'.findAll()','system.db.ar.CActiveRecord');
$criteria=$this->getCommandBuilder()->createCriteria($condition,$params);
return $this->query($criteria,true);
}
Finds all active records satisfying the specified condition. See find() for detailed explanation about $condition and $params.
findAllByAttributes() method
public static[] findAllByAttributes(array $attributes, mixed $condition='', array $params=array ( )) | ||
$attributes | array | list of attribute values (indexed by attribute names) that the active records should match. An attribute value can be an array which will be used to generate an IN condition. |
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | static[] | the records found. An empty array is returned if none is found. |
public function findAllByAttributes($attributes,$condition='',$params=array())
{
Yii::trace(get_class($this).'.findAllByAttributes()','system.db.ar.CActiveRecord');
$prefix=$this->getTableAlias(true).'.';
$criteria=$this->getCommandBuilder()->createColumnCriteria($this->getTableSchema(),$attributes,$condition,$params,$prefix);
return $this->query($criteria,true);
}
Finds all active records that have the specified attribute values. See find() for detailed explanation about $condition and $params.
findAllByPk() method
public static[] findAllByPk(mixed $pk, mixed $condition='', array $params=array ( )) | ||
$pk | mixed | primary key value(s). Use array for multiple primary keys. For composite key, each key value must be an array (column name=>column value). |
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | static[] | the records found. An empty array is returned if none is found. |
public function findAllByPk($pk,$condition='',$params=array())
{
Yii::trace(get_class($this).'.findAllByPk()','system.db.ar.CActiveRecord');
$prefix=$this->getTableAlias(true).'.';
$criteria=$this->getCommandBuilder()->createPkCriteria($this->getTableSchema(),$pk,$condition,$params,$prefix);
return $this->query($criteria,true);
}
Finds all active records with the specified primary keys. See find() for detailed explanation about $condition and $params.
findAllBySql() method
public static[] findAllBySql(string $sql, array $params=array ( )) | ||
$sql | string | the SQL statement |
$params | array | parameters to be bound to the SQL statement |
{return} | static[] | the records found. An empty array is returned if none is found. |
public function findAllBySql($sql,$params=array())
{
Yii::trace(get_class($this).'.findAllBySql()','system.db.ar.CActiveRecord');
$this->beforeFind();
if(($criteria=$this->getDbCriteria(false))!==null && !empty($criteria->with))
{
$this->resetScope(false);
$finder=$this->getActiveFinder($criteria->with);
return $finder->findAllBySql($sql,$params);
}
else
{
$command=$this->getCommandBuilder()->createSqlCommand($sql,$params);
return $this->populateRecords($command->queryAll());
}
}
Finds all active records using the specified SQL statement.
findByAttributes() method
public static findByAttributes(array $attributes, mixed $condition='', array $params=array ( )) | ||
$attributes | array | list of attribute values (indexed by attribute names) that the active records should match. An attribute value can be an array which will be used to generate an IN condition. |
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | static | the record found. Null if none is found. |
public function findByAttributes($attributes,$condition='',$params=array())
{
Yii::trace(get_class($this).'.findByAttributes()','system.db.ar.CActiveRecord');
$prefix=$this->getTableAlias(true).'.';
$criteria=$this->getCommandBuilder()->createColumnCriteria($this->getTableSchema(),$attributes,$condition,$params,$prefix);
return $this->query($criteria);
}
Finds a single active record that has the specified attribute values. See find() for detailed explanation about $condition and $params.
findByPk() method
public static findByPk(mixed $pk, mixed $condition='', array $params=array ( )) | ||
$pk | mixed | primary key value(s). Use array for multiple primary keys. For composite key, each key value must be an array (column name=>column value). |
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | static | the record found. Null if none is found. |
public function findByPk($pk,$condition='',$params=array())
{
Yii::trace(get_class($this).'.findByPk()','system.db.ar.CActiveRecord');
$prefix=$this->getTableAlias(true).'.';
$criteria=$this->getCommandBuilder()->createPkCriteria($this->getTableSchema(),$pk,$condition,$params,$prefix);
return $this->query($criteria);
}
Finds a single active record with the specified primary key. See find() for detailed explanation about $condition and $params.
findBySql() method
public static findBySql(string $sql, array $params=array ( )) | ||
$sql | string | the SQL statement |
$params | array | parameters to be bound to the SQL statement |
{return} | static | the record found. Null if none is found. |
public function findBySql($sql,$params=array())
{
Yii::trace(get_class($this).'.findBySql()','system.db.ar.CActiveRecord');
$this->beforeFind();
if(($criteria=$this->getDbCriteria(false))!==null && !empty($criteria->with))
{
$this->resetScope(false);
$finder=$this->getActiveFinder($criteria->with);
return $finder->findBySql($sql,$params);
}
else
{
$command=$this->getCommandBuilder()->createSqlCommand($sql,$params);
return $this->populateRecord($command->queryRow());
}
}
Finds a single active record with the specified SQL statement.
getActiveFinder() method (available since v1.1.14)
public CActiveFinder getActiveFinder(mixed $with) | ||
$with | mixed | the relation names to be actively looked for |
{return} | CActiveFinder | active finder for the operation |
public function getActiveFinder($with)
{
return new CActiveFinder($this,$with);
}
Given 'with' options returns a new active finder instance.
getActiveRelation() method
public CActiveRelation getActiveRelation(string $name) | ||
$name | string | the relation name |
{return} | CActiveRelation | the named relation declared for this AR class. Null if the relation does not exist. |
public function getActiveRelation($name)
{
return isset($this->getMetaData()->relations[$name]) ? $this->getMetaData()->relations[$name] : null;
}
Returns the named relation declared for this AR class.
getAttribute() method
public mixed getAttribute(string $name) | ||
$name | string | the attribute name |
{return} | mixed | the attribute value. Null if the attribute is not set or does not exist. |
public function getAttribute($name)
{
if(property_exists($this,$name))
return $this->$name;
elseif(isset($this->_attributes[$name]))
return $this->_attributes[$name];
}
Returns the named attribute value. If this is a new record and the attribute is not set before, the default column value will be returned. If this record is the result of a query and the attribute is not loaded, null will be returned. You may also use $this->AttributeName to obtain the attribute value.
See Also
getAttributeLabel() method (available since v1.1.4)
public string getAttributeLabel(string $attribute) | ||
$attribute | string | the attribute name |
{return} | string | the attribute label |
public function getAttributeLabel($attribute)
{
$labels=$this->attributeLabels();
if(isset($labels[$attribute]))
return $labels[$attribute];
elseif(strpos($attribute,'.')!==false)
{
$segs=explode('.',$attribute);
$name=array_pop($segs);
$model=$this;
foreach($segs as $seg)
{
$relations=$model->getMetaData()->relations;
if(isset($relations[$seg]))
$model=CActiveRecord::model($relations[$seg]->className);
else
break;
}
return $model->getAttributeLabel($name);
}
else
return $this->generateAttributeLabel($attribute);
}
Returns the text label for the specified attribute. This method overrides the parent implementation by supporting returning the label defined in relational object. In particular, if the attribute name is in the form of "post.author.name", then this method will derive the label from the "author" relation's "name" attribute.
See Also
getAttributes() method
public array getAttributes(mixed $names=true) | ||
$names | mixed | names of attributes whose value needs to be returned. If this is true (default), then all attribute values will be returned, including those that are not loaded from DB (null will be returned for those attributes). If this is null, all attributes except those that are not loaded from DB will be returned. |
{return} | array | attribute values indexed by attribute names. |
public function getAttributes($names=true)
{
$attributes=$this->_attributes;
foreach($this->getMetaData()->columns as $name=>$column)
{
if(property_exists($this,$name))
$attributes[$name]=$this->$name;
elseif($names===true && !isset($attributes[$name]))
$attributes[$name]=null;
}
if(is_array($names))
{
$attrs=array();
foreach($names as $name)
{
if(property_exists($this,$name))
$attrs[$name]=$this->$name;
else
$attrs[$name]=isset($attributes[$name])?$attributes[$name]:null;
}
return $attrs;
}
else
return $attributes;
}
Returns all column attribute values. Note, related objects are not returned.
getCommandBuilder() method
public CDbCommandBuilder getCommandBuilder() | ||
{return} | CDbCommandBuilder | the command builder used by this AR |
public function getCommandBuilder()
{
return $this->getDbConnection()->getSchema()->getCommandBuilder();
}
Returns the command builder used by this AR.
getDbConnection() method
public CDbConnection getDbConnection() | ||
{return} | CDbConnection | the database connection used by active record. |
public function getDbConnection()
{
if(self::$db!==null)
return self::$db;
else
{
self::$db=Yii::app()->getDb();
if(self::$db instanceof CDbConnection)
return self::$db;
else
throw new CDbException(Yii::t('yii','Active Record requires a "db" CDbConnection application component.'));
}
}
Returns the database connection used by active record. By default, the "db" application component is used as the database connection. You may override this method if you want to use a different database connection.
getDbCriteria() method
public CDbCriteria getDbCriteria(boolean $createIfNull=true) | ||
$createIfNull | boolean | whether to create a criteria instance if it does not exist. Defaults to true. |
{return} | CDbCriteria | the query criteria that is associated with this model. This criteria is mainly used by named scope feature to accumulate different criteria specifications. |
public function getDbCriteria($createIfNull=true)
{
if($this->_c===null)
{
if(($c=$this->defaultScope())!==array() || $createIfNull)
$this->_c=new CDbCriteria($c);
}
return $this->_c;
}
Returns the query criteria associated with this model.
getIsNewRecord() method
public boolean getIsNewRecord() | ||
{return} | boolean | whether the record is new and should be inserted when calling save. This property is automatically set in constructor and populateRecord and is set to false right after inserting record to database. Defaults to false, but it will be set to true if the instance is created using the new operator. |
public function getIsNewRecord()
{
return $this->_new;
}
Returns if the current record is new (was never saved to database)
getMetaData() method
public CActiveRecordMetaData getMetaData() | ||
{return} | CActiveRecordMetaData | the meta for this AR class. |
public function getMetaData()
{
$className=get_class($this);
if(!array_key_exists($className,self::$_md))
{
self::$_md[$className]=null; // preventing recursive invokes of {@link getMetaData()} via {@link __get()}
self::$_md[$className]=new CActiveRecordMetaData($this);
}
return self::$_md[$className];
}
Returns the meta-data for this AR
getOldPrimaryKey() method (available since v1.1.0)
public mixed getOldPrimaryKey() | ||
{return} | mixed | the old primary key value. An array (column name=>column value) is returned if the primary key is composite. If primary key is not defined, null will be returned. |
public function getOldPrimaryKey()
{
return $this->_pk;
}
Returns the old primary key value. This refers to the primary key value that is populated into the record after executing a find method (e.g. find(), findAll()). The value remains unchanged even if the primary key attribute is manually assigned with a different value.
getPrimaryKey() method
public mixed getPrimaryKey() | ||
{return} | mixed | the primary key value. An array (column name=>column value) is returned if the primary key is composite. If primary key is not defined, null will be returned. |
public function getPrimaryKey()
{
$table=$this->getTableSchema();
if(is_string($table->primaryKey))
return $this->{$table->primaryKey};
elseif(is_array($table->primaryKey))
{
$values=array();
foreach($table->primaryKey as $name)
$values[$name]=$this->$name;
return $values;
}
else
return null;
}
Returns the primary key value.
getRelated() method
public mixed getRelated(string $name, boolean $refresh=false, mixed $params=array ( )) | ||
$name | string | the relation name (see relations) |
$refresh | boolean | whether to reload the related objects from database. Defaults to false. If the current record is not a new record and it does not have the related objects loaded they will be retrieved from the database even if this is set to false. If the current record is a new record and this value is false, the related objects will not be retrieved from the database. |
$params | mixed | array or CDbCriteria object with additional parameters that customize the query conditions as specified in the relation declaration. If this is supplied the related record(s) will be retrieved from the database regardless of the value or $refresh. The related record(s) retrieved when this is supplied will only be returned by this method and will not be loaded into the current record's relation. The value of the relation prior to running this method will still be available for the current record if this is supplied. |
{return} | mixed | the related object(s). |
public function getRelated($name,$refresh=false,$params=array())
{
if(!$refresh && $params===array() && (isset($this->_related[$name]) || array_key_exists($name,$this->_related)))
return $this->_related[$name];
$md=$this->getMetaData();
if(!isset($md->relations[$name]))
throw new CDbException(Yii::t('yii','{class} does not have relation "{name}".',
array('{class}'=>get_class($this), '{name}'=>$name)));
Yii::trace('lazy loading '.get_class($this).'.'.$name,'system.db.ar.CActiveRecord');
$relation=$md->relations[$name];
if($this->getIsNewRecord() && !$refresh && ($relation instanceof CHasOneRelation || $relation instanceof CHasManyRelation))
return $relation instanceof CHasOneRelation ? null : array();
if($params!==array()) // dynamic query
{
$exists=isset($this->_related[$name]) || array_key_exists($name,$this->_related);
if($exists)
$save=$this->_related[$name];
if($params instanceof CDbCriteria)
$params = $params->toArray();
$r=array($name=>$params);
}
else
$r=$name;
unset($this->_related[$name]);
$finder=$this->getActiveFinder($r);
$finder->lazyFind($this);
if(!isset($this->_related[$name]))
{
if($relation instanceof CHasManyRelation)
$this->_related[$name]=array();
elseif($relation instanceof CStatRelation)
$this->_related[$name]=$relation->defaultValue;
else
$this->_related[$name]=null;
}
if($params!==array())
{
$results=$this->_related[$name];
if($exists)
$this->_related[$name]=$save;
else
unset($this->_related[$name]);
return $results;
}
else
return $this->_related[$name];
}
Returns the related record(s). This method will return the related record(s) of the current record. If the relation is HAS_ONE or BELONGS_TO, it will return a single object or null if the object does not exist. If the relation is HAS_MANY or MANY_MANY, it will return an array of objects or an empty array.
getTableAlias() method (available since v1.1.1)
public string getTableAlias(boolean $quote=false, boolean $checkScopes=true) | ||
$quote | boolean | whether to quote the alias name |
$checkScopes | boolean | whether to check if a table alias is defined in the applied scopes so far. This parameter must be set false when calling this method in defaultScope. An infinite loop would be formed otherwise. |
{return} | string | the default table alias |
public function getTableAlias($quote=false, $checkScopes=true)
{
if($checkScopes && ($criteria=$this->getDbCriteria(false))!==null && $criteria->alias!='')
$alias=$criteria->alias;
else
$alias=$this->_alias;
return $quote ? $this->getDbConnection()->getSchema()->quoteTableName($alias) : $alias;
}
Returns the table alias to be used by the find methods. In relational queries, the returned table alias may vary according to the corresponding relation declaration. Also, the default table alias set by setTableAlias may be overridden by the applied scopes.
getTableSchema() method
public CDbTableSchema getTableSchema() | ||
{return} | CDbTableSchema | the metadata of the table that this AR belongs to |
public function getTableSchema()
{
return $this->getMetaData()->tableSchema;
}
Returns the metadata of the table that this AR belongs to
hasAttribute() method
public boolean hasAttribute(string $name) | ||
$name | string | attribute name |
{return} | boolean | whether this AR has the named attribute (table column). |
public function hasAttribute($name)
{
return isset($this->getMetaData()->columns[$name]);
}
Checks whether this AR has the named attribute
hasRelated() method
public boolean hasRelated(string $name) | ||
$name | string | the relation name |
{return} | boolean | a value indicating whether the named related object(s) has been loaded. |
public function hasRelated($name)
{
return isset($this->_related[$name]) || array_key_exists($name,$this->_related);
}
Returns a value indicating whether the named related object(s) has been loaded.
init() method
public void init() |
Initializes this model. This method is invoked when an AR instance is newly created and has its scenario set. You may override this method to provide code that is needed to initialize the model (e.g. setting initial property values.)
insert() method
public boolean insert(array $attributes=NULL) | ||
$attributes | array | list of attributes that need to be saved. Defaults to null, meaning all attributes that are loaded from DB will be saved. |
{return} | boolean | whether the attributes are valid and the record is inserted successfully. |
public function insert($attributes=null)
{
if(!$this->getIsNewRecord())
throw new CDbException(Yii::t('yii','The active record cannot be inserted to database because it is not new.'));
if($this->beforeSave())
{
Yii::trace(get_class($this).'.insert()','system.db.ar.CActiveRecord');
$builder=$this->getCommandBuilder();
$table=$this->getTableSchema();
$command=$builder->createInsertCommand($table,$this->getAttributes($attributes));
if($command->execute())
{
$primaryKey=$table->primaryKey;
if($table->sequenceName!==null)
{
if(is_string($primaryKey) && $this->$primaryKey===null)
$this->$primaryKey=$builder->getLastInsertID($table);
elseif(is_array($primaryKey))
{
foreach($primaryKey as $pk)
{
if($this->$pk===null)
{
$this->$pk=$builder->getLastInsertID($table);
break;
}
}
}
}
$this->_pk=$this->getPrimaryKey();
$this->afterSave();
$this->setIsNewRecord(false);
$this->setScenario('update');
return true;
}
}
return false;
}
Inserts a row into the table based on this active record attributes. If the table's primary key is auto-incremental and is null before insertion, it will be populated with the actual value after insertion. Note, validation is not performed in this method. You may call validate to perform the validation. After the record is inserted to DB successfully, its isNewRecord property will be set false, and its scenario property will be set to be 'update'.
instantiate() method
protected static instantiate(array $attributes) | ||
$attributes | array | list of attribute values for the active records. |
{return} | static | the active record |
protected function instantiate($attributes)
{
$class=get_class($this);
$model=new $class(null);
return $model;
}
Creates an active record instance. This method is called by populateRecord and populateRecords. You may override this method if the instance being created depends the attributes that are to be populated to the record. For example, by creating a record based on the value of a column, you may implement the so-called single-table inheritance mapping.
model() method
public static static model(string $className='CActiveRecord') | ||
$className | string | active record class name. |
{return} | static | active record model instance. |
public static function model($className=__CLASS__)
{
if(isset(self::$_models[$className]))
return self::$_models[$className];
else
{
$model=self::$_models[$className]=new $className(null);
$model->attachBehaviors($model->behaviors());
return $model;
}
}
Returns the static model of the specified AR class. The model returned is a static instance of the AR class. It is provided for invoking class-level methods (something similar to static class methods.)
EVERY derived AR class must override this method as follows,
public static function model($className=__CLASS__) { return parent::model($className); }
offsetExists() method
public boolean offsetExists(mixed $offset) | ||
$offset | mixed | the offset to check on |
{return} | boolean |
public function offsetExists($offset)
{
return $this->__isset($offset);
}
Returns whether there is an element at the specified offset. This method is required by the interface ArrayAccess.
onAfterDelete() method
public void onAfterDelete(CEvent $event) | ||
$event | CEvent | the event parameter |
public function onAfterDelete($event)
{
$this->raiseEvent('onAfterDelete',$event);
}
This event is raised after the record is deleted.
onAfterFind() method
public void onAfterFind(CEvent $event) | ||
$event | CEvent | the event parameter |
public function onAfterFind($event)
{
$this->raiseEvent('onAfterFind',$event);
}
This event is raised after the record is instantiated by a find method.
onAfterSave() method
public void onAfterSave(CEvent $event) | ||
$event | CEvent | the event parameter |
public function onAfterSave($event)
{
$this->raiseEvent('onAfterSave',$event);
}
This event is raised after the record is saved.
onBeforeCount() method (available since v1.1.14)
public void onBeforeCount(CModelEvent $event) | ||
$event | CModelEvent | the event parameter |
public function onBeforeCount($event)
{
$this->raiseEvent('onBeforeCount',$event);
}
This event is raised before an AR finder performs a count call. If you want to access or modify the query criteria used for the count call, you can use getDbCriteria() to customize it based on your needs. When modifying criteria in beforeCount you have to make sure you are using the right table alias which is different on normal count and relational call. You can use getTableAlias() to get the alias used for the upcoming count call.
See Also
onBeforeDelete() method
public void onBeforeDelete(CModelEvent $event) | ||
$event | CModelEvent | the event parameter |
public function onBeforeDelete($event)
{
$this->raiseEvent('onBeforeDelete',$event);
}
This event is raised before the record is deleted. By setting CModelEvent::isValid to be false, the normal delete() process will be stopped.
onBeforeFind() method
public void onBeforeFind(CModelEvent $event) | ||
$event | CModelEvent | the event parameter |
public function onBeforeFind($event)
{
$this->raiseEvent('onBeforeFind',$event);
}
This event is raised before an AR finder performs a find call. This can be either a call to CActiveRecords find methods or a find call when model is loaded in relational context via lazy or eager loading. If you want to access or modify the query criteria used for the find call, you can use getDbCriteria() to customize it based on your needs. When modifying criteria in beforeFind you have to make sure you are using the right table alias which is different on normal find and relational call. You can use getTableAlias() to get the alias used for the upcoming find call. Please note that modification of criteria is fully supported as of version 1.1.13. Earlier versions had some problems with relational context and applying changes correctly.
See Also
onBeforeSave() method
public void onBeforeSave(CModelEvent $event) | ||
$event | CModelEvent | the event parameter |
public function onBeforeSave($event)
{
$this->raiseEvent('onBeforeSave',$event);
}
This event is raised before the record is saved. By setting CModelEvent::isValid to be false, the normal save() process will be stopped.
populateRecord() method
public static populateRecord(array $attributes, boolean $callAfterFind=true) | ||
$attributes | array | attribute values (column name=>column value) |
$callAfterFind | boolean | whether to call afterFind after the record is populated. |
{return} | static | the newly created active record. The class of the object is the same as the model class. Null is returned if the input data is false. |
public function populateRecord($attributes,$callAfterFind=true)
{
if($attributes!==false)
{
$record=$this->instantiate($attributes);
$record->setScenario('update');
$record->init();
$md=$record->getMetaData();
foreach($attributes as $name=>$value)
{
if(property_exists($record,$name))
$record->$name=$value;
elseif(isset($md->columns[$name]))
$record->_attributes[$name]=$value;
}
$record->_pk=$record->getPrimaryKey();
$record->attachBehaviors($record->behaviors());
if($callAfterFind)
$record->afterFind();
return $record;
}
else
return null;
}
Creates an active record with the given attributes. This method is internally used by the find methods.
populateRecords() method
public static[] populateRecords(array $data, boolean $callAfterFind=true, string $index=NULL) | ||
$data | array | list of attribute values for the active records. |
$callAfterFind | boolean | whether to call afterFind after each record is populated. |
$index | string | the name of the attribute whose value will be used as indexes of the query result array. If null, it means the array will be indexed by zero-based integers. |
{return} | static[] | list of active records. |
public function populateRecords($data,$callAfterFind=true,$index=null)
{
$records=array();
foreach($data as $attributes)
{
if(($record=$this->populateRecord($attributes,$callAfterFind))!==null)
{
if($index===null)
$records[]=$record;
else
$records[$record->$index]=$record;
}
}
return $records;
}
Creates a list of active records based on the input data. This method is internally used by the find methods.
primaryKey() method
public mixed primaryKey() | ||
{return} | mixed | the primary key of the associated database table. If the key is a single column, it should return the column name; If the key is a composite one consisting of several columns, it should return the array of the key column names. |
Returns the primary key of the associated database table. This method is meant to be overridden in case when the table is not defined with a primary key (for some legency database). If the table is already defined with a primary key, you do not need to override this method. The default implementation simply returns null, meaning using the primary key defined in the database.
query() method (available since v1.1.7)
protected mixed query(CDbCriteria $criteria, boolean $all=false) | ||
$criteria | CDbCriteria | the query criteria |
$all | boolean | whether to return all data |
{return} | mixed | the AR objects populated with the query result |
protected function query($criteria,$all=false)
{
$this->beforeFind();
$this->applyScopes($criteria);
if(empty($criteria->with))
{
if(!$all)
$criteria->limit=1;
$command=$this->getCommandBuilder()->createFindCommand($this->getTableSchema(),$criteria);
return $all ? $this->populateRecords($command->queryAll(), true, $criteria->index) : $this->populateRecord($command->queryRow());
}
else
{
$finder=$this->getActiveFinder($criteria->with);
return $finder->query($criteria,$all);
}
}
Performs the actual DB query and populates the AR objects with the query result. This method is mainly internally used by other AR query methods.
refresh() method
public boolean refresh() | ||
{return} | boolean | whether the row still exists in the database. If true, the latest data will be populated to this active record. |
public function refresh()
{
Yii::trace(get_class($this).'.refresh()','system.db.ar.CActiveRecord');
if(($record=$this->findByPk($this->getPrimaryKey()))!==null)
{
$this->_attributes=array();
$this->_related=array();
foreach($this->getMetaData()->columns as $name=>$column)
{
if(property_exists($this,$name))
$this->$name=$record->$name;
else
$this->_attributes[$name]=$record->$name;
}
return true;
}
else
return false;
}
Repopulates this active record with the latest data.
refreshMetaData() method
public void refreshMetaData() |
public function refreshMetaData()
{
$className=get_class($this);
if(array_key_exists($className,self::$_md))
unset(self::$_md[$className]);
}
Refreshes the meta data for this AR class. By calling this method, this AR class will regenerate the meta data needed. This is useful if the table schema has been changed and you want to use the latest available table schema. Make sure you have called CDbSchema::refresh before you call this method. Otherwise, old table schema data will still be used.
relations() method
public array relations() | ||
{return} | array | list of related object declarations. Defaults to empty array. |
public function relations()
{
return array();
}
This method should be overridden to declare related objects.
There are four types of relations that may exist between two active record objects:
- BELONGS_TO: e.g. a member belongs to a team;
- HAS_ONE: e.g. a member has at most one profile;
- HAS_MANY: e.g. a team has many members;
- MANY_MANY: e.g. a member has many skills and a skill belongs to a member.
Besides the above relation types, a special relation called STAT is also supported that can be used to perform statistical query (or aggregational query). It retrieves the aggregational information about the related objects, such as the number of comments for each post, the average rating for each product, etc.
Each kind of related objects is defined in this method as an array with the following elements:
'varName'=>array('relationType', 'className', 'foreignKey', ...additional options)where 'varName' refers to the name of the variable/property that the related object(s) can be accessed through; 'relationType' refers to the type of the relation, which can be one of the following four constants: self::BELONGS_TO, self::HAS_ONE, self::HAS_MANY and self::MANY_MANY; 'className' refers to the name of the active record class that the related object(s) is of; and 'foreignKey' states the foreign key that relates the two kinds of active record. Note, for composite foreign keys, they can be either listed together, separated by commas or specified as an array in format of array('key1','key2'). In case you need to specify custom PK->FK association you can define it as array('fk'=>'pk'). For composite keys it will be array('fk_c1'=>'pk_с1','fk_c2'=>'pk_c2'). For foreign keys used in MANY_MANY relation, the joining table must be declared as well (e.g. 'join_table(fk1, fk2)').
Additional options may be specified as name-value pairs in the rest array elements:
- 'select': string|array, a list of columns to be selected. Defaults to '*', meaning all columns. Column names should be disambiguated if they appear in an expression (e.g. COUNT(relationName.name) AS name_count).
- 'condition': string, the WHERE clause. Defaults to empty. Note, column references need to be disambiguated with prefix 'relationName.' (e.g. relationName.age>20)
- 'order': string, the ORDER BY clause. Defaults to empty. Note, column references need to be disambiguated with prefix 'relationName.' (e.g. relationName.age DESC)
- 'with': string|array, a list of child related objects that should be loaded together with this object. Note, this is only honored by lazy loading, not eager loading.
- 'joinType': type of join. Defaults to 'LEFT OUTER JOIN'.
- 'alias': the alias for the table associated with this relationship. It defaults to null, meaning the table alias is the same as the relation name.
- 'params': the parameters to be bound to the generated SQL statement. This should be given as an array of name-value pairs.
- 'on': the ON clause. The condition specified here will be appended to the joining condition using the AND operator.
- 'index': the name of the column whose values should be used as keys of the array that stores related objects. This option is only available to HAS_MANY and MANY_MANY relations.
- 'scopes': scopes to apply. In case of a single scope can be used like 'scopes'=>'scopeName', in case of multiple scopes can be used like 'scopes'=>array('scopeName1','scopeName2'). This option has been available since version 1.1.9.
The following options are available for certain relations when lazy loading:
- 'group': string, the GROUP BY clause. Defaults to empty. Note, column references need to be disambiguated with prefix 'relationName.' (e.g. relationName.age). This option only applies to HAS_MANY and MANY_MANY relations.
- 'having': string, the HAVING clause. Defaults to empty. Note, column references need to be disambiguated with prefix 'relationName.' (e.g. relationName.age). This option only applies to HAS_MANY and MANY_MANY relations.
- 'limit': limit of the rows to be selected. This option does not apply to BELONGS_TO relation.
- 'offset': offset of the rows to be selected. This option does not apply to BELONGS_TO relation.
- 'through': name of the model's relation that will be used as a bridge when getting related data. Can be set only for HAS_ONE and HAS_MANY. This option has been available since version 1.1.7.
Below is an example declaring related objects for 'Post' active record class:
return array( 'author'=>array(self::BELONGS_TO, 'User', 'author_id'), 'comments'=>array(self::HAS_MANY, 'Comment', 'post_id', 'with'=>'author', 'order'=>'create_time DESC'), 'tags'=>array(self::MANY_MANY, 'Tag', 'post_tag(post_id, tag_id)', 'order'=>'name'), );
resetScope() method (available since v1.1.2)
public static resetScope(boolean $resetDefault=true) | ||
$resetDefault | boolean | including default scope. This parameter available since 1.1.12 |
{return} | static | the AR instance itself |
public function resetScope($resetDefault=true)
{
if($resetDefault)
$this->_c=new CDbCriteria();
else
$this->_c=null;
return $this;
}
Resets all scopes and criterias applied.
save() method
public boolean save(boolean $runValidation=true, array $attributes=NULL) | ||
$runValidation | boolean | whether to perform validation before saving the record. If the validation fails, the record will not be saved to database. |
$attributes | array | list of attributes that need to be saved. Defaults to null, meaning all attributes that are loaded from DB will be saved. |
{return} | boolean | whether the saving succeeds |
public function save($runValidation=true,$attributes=null)
{
if(!$runValidation || $this->validate($attributes))
return $this->getIsNewRecord() ? $this->insert($attributes) : $this->update($attributes);
else
return false;
}
Saves the current record.
The record is inserted as a row into the database table if its isNewRecord property is true (usually the case when the record is created using the 'new' operator). Otherwise, it will be used to update the corresponding row in the table (usually the case if the record is obtained using one of those 'find' methods.)
Validation will be performed before saving the record. If the validation fails, the record will not be saved. You can call getErrors() to retrieve the validation errors.
If the record is saved via insertion, its isNewRecord property will be set false, and its scenario property will be set to be 'update'. And if its primary key is auto-incremental and is not set before insertion, the primary key will be populated with the automatically generated key value.
saveAttributes() method
public boolean saveAttributes(array $attributes) | ||
$attributes | array | attributes to be updated. Each element represents an attribute name or an attribute value indexed by its name. If the latter, the record's attribute will be changed accordingly before saving. |
{return} | boolean | whether the update is successful. Note that false is also returned if the saving was successfull but no attributes had changed and the database driver returns 0 for the number of updated records. |
public function saveAttributes($attributes)
{
if(!$this->getIsNewRecord())
{
Yii::trace(get_class($this).'.saveAttributes()','system.db.ar.CActiveRecord');
$values=array();
foreach($attributes as $name=>$value)
{
if(is_integer($name))
$values[$value]=$this->$value;
else
$values[$name]=$this->$name=$value;
}
if($this->_pk===null)
$this->_pk=$this->getPrimaryKey();
if($this->updateByPk($this->getOldPrimaryKey(),$values)>0)
{
$this->_pk=$this->getPrimaryKey();
return true;
}
else
return false;
}
else
throw new CDbException(Yii::t('yii','The active record cannot be updated because it is new.'));
}
Saves a selected list of attributes. Unlike save, this method only saves the specified attributes of an existing row dataset and does NOT call either beforeSave or afterSave. Also note that this method does neither attribute filtering nor validation. So do not use this method with untrusted data (such as user posted data). You may consider the following alternative if you want to do so:
$postRecord=Post::model()->findByPk($postID); $postRecord->attributes=$_POST['post']; $postRecord->save();
saveCounters() method (available since v1.1.8)
public boolean saveCounters(array $counters) | ||
$counters | array | the counters to be updated (column name=>increment value) |
{return} | boolean | whether the saving is successful |
public function saveCounters($counters)
{
Yii::trace(get_class($this).'.saveCounters()','system.db.ar.CActiveRecord');
$builder=$this->getCommandBuilder();
$table=$this->getTableSchema();
$criteria=$builder->createPkCriteria($table,$this->getOldPrimaryKey());
$command=$builder->createUpdateCounterCommand($this->getTableSchema(),$counters,$criteria);
if($command->execute())
{
foreach($counters as $name=>$value)
$this->$name=$this->$name+$value;
return true;
}
else
return false;
}
Saves one or several counter columns for the current AR object. Note that this method differs from updateCounters in that it only saves the current AR object. An example usage is as follows:
$postRecord=Post::model()->findByPk($postID); $postRecord->saveCounters(array('view_count'=>1));Use negative values if you want to decrease the counters.
See Also
scopes() method
public array scopes() | ||
{return} | array | the scope definition. The array keys are scope names; the array values are the corresponding scope definitions. Each scope definition is represented as an array whose keys must be properties of CDbCriteria. |
public function scopes()
{
return array();
}
Returns the declaration of named scopes. A named scope represents a query criteria that can be chained together with other named scopes and applied to a query. This method should be overridden by child classes to declare named scopes for the particular AR classes. For example, the following code declares two named scopes: 'recently' and 'published'.
return array( 'published'=>array( 'condition'=>'status=1', ), 'recently'=>array( 'order'=>'create_time DESC', 'limit'=>5, ), );If the above scopes are declared in a 'Post' model, we can perform the following queries:
$posts=Post::model()->published()->findAll(); $posts=Post::model()->published()->recently()->findAll(); $posts=Post::model()->published()->with('comments')->findAll();Note that the last query is a relational query.
setAttribute() method
public boolean setAttribute(string $name, mixed $value) | ||
$name | string | the attribute name |
$value | mixed | the attribute value. |
{return} | boolean | whether the attribute exists and the assignment is conducted successfully |
public function setAttribute($name,$value)
{
if(property_exists($this,$name))
$this->$name=$value;
elseif(isset($this->getMetaData()->columns[$name]))
$this->_attributes[$name]=$value;
else
return false;
return true;
}
Sets the named attribute value. You may also use $this->AttributeName to set the attribute value.
See Also
setDbCriteria() method (available since v1.1.3)
public void setDbCriteria(CDbCriteria $criteria) | ||
$criteria | CDbCriteria | the query criteria |
public function setDbCriteria($criteria)
{
$this->_c=$criteria;
}
Sets the query criteria for the current model.
setIsNewRecord() method
public void setIsNewRecord(boolean $value) | ||
$value | boolean | whether the record is new and should be inserted when calling save. |
public function setIsNewRecord($value)
{
$this->_new=$value;
}
Sets if the record is new.
See Also
setOldPrimaryKey() method (available since v1.1.3)
public void setOldPrimaryKey(mixed $value) | ||
$value | mixed | the old primary key value. |
public function setOldPrimaryKey($value)
{
$this->_pk=$value;
}
Sets the old primary key value.
setPrimaryKey() method (available since v1.1.0)
public void setPrimaryKey(mixed $value) | ||
$value | mixed | the new primary key value. If the primary key is composite, the new value should be provided as an array (column name=>column value). |
public function setPrimaryKey($value)
{
$this->_pk=$this->getPrimaryKey();
$table=$this->getTableSchema();
if(is_string($table->primaryKey))
$this->{$table->primaryKey}=$value;
elseif(is_array($table->primaryKey))
{
foreach($table->primaryKey as $name)
$this->$name=$value[$name];
}
}
Sets the primary key value. After calling this method, the old primary key value can be obtained from oldPrimaryKey.
setTableAlias() method (available since v1.1.3)
public void setTableAlias(string $alias) | ||
$alias | string | the table alias to be used in queries. The alias should NOT be quoted. |
public function setTableAlias($alias)
{
$this->_alias=$alias;
}
Sets the table alias to be used in queries.
tableName() method
public string tableName() | ||
{return} | string | the table name |
public function tableName()
{
$tableName = get_class($this);
if(($pos=strrpos($tableName,'\\')) !== false)
return substr($tableName,$pos+1);
return $tableName;
}
Returns the name of the associated database table. By default this method returns the class name as the table name. You may override this method if the table is not named after this convention.
together() method (available since v1.1.4)
public static together() | ||
{return} | static | the AR object itself |
public function together()
{
$this->getDbCriteria()->together=true;
return $this;
}
Sets CDbCriteria::together property to be true. This is only used in relational AR query. Please refer to CDbCriteria::together for more details.
update() method
public boolean update(array $attributes=NULL) | ||
$attributes | array | list of attributes that need to be saved. Defaults to null, meaning all attributes that are loaded from DB will be saved. |
{return} | boolean | whether the update is successful |
public function update($attributes=null)
{
if($this->getIsNewRecord())
throw new CDbException(Yii::t('yii','The active record cannot be updated because it is new.'));
if($this->beforeSave())
{
Yii::trace(get_class($this).'.update()','system.db.ar.CActiveRecord');
if($this->_pk===null)
$this->_pk=$this->getPrimaryKey();
$this->updateByPk($this->getOldPrimaryKey(),$this->getAttributes($attributes));
$this->_pk=$this->getPrimaryKey();
$this->afterSave();
return true;
}
else
return false;
}
Updates the row represented by this active record. All loaded attributes will be saved to the database. Note, validation is not performed in this method. You may call validate to perform the validation.
updateAll() method
public integer updateAll(array $attributes, mixed $condition='', array $params=array ( )) | ||
$attributes | array | list of attributes (name=>$value) to be updated |
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | integer | the number of rows being updated |
public function updateAll($attributes,$condition='',$params=array())
{
Yii::trace(get_class($this).'.updateAll()','system.db.ar.CActiveRecord');
$builder=$this->getCommandBuilder();
$criteria=$builder->createCriteria($condition,$params);
$command=$builder->createUpdateCommand($this->getTableSchema(),$attributes,$criteria);
return $command->execute();
}
Updates records with the specified condition. See find() for detailed explanation about $condition and $params. Note, the attributes are not checked for safety and no validation is done.
updateByPk() method
public integer updateByPk(mixed $pk, array $attributes, mixed $condition='', array $params=array ( )) | ||
$pk | mixed | primary key value(s). Use array for multiple primary keys. For composite key, each key value must be an array (column name=>column value). |
$attributes | array | list of attributes (name=>$value) to be updated |
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | integer | the number of rows being updated |
public function updateByPk($pk,$attributes,$condition='',$params=array())
{
Yii::trace(get_class($this).'.updateByPk()','system.db.ar.CActiveRecord');
$builder=$this->getCommandBuilder();
$table=$this->getTableSchema();
$criteria=$builder->createPkCriteria($table,$pk,$condition,$params);
$command=$builder->createUpdateCommand($table,$attributes,$criteria);
return $command->execute();
}
Updates records with the specified primary key(s). See find() for detailed explanation about $condition and $params. Note, the attributes are not checked for safety and validation is NOT performed.
updateCounters() method
public integer updateCounters(array $counters, mixed $condition='', array $params=array ( )) | ||
$counters | array | the counters to be updated (column name=>increment value) |
$condition | mixed | query condition or criteria. |
$params | array | parameters to be bound to an SQL statement. |
{return} | integer | the number of rows being updated |
public function updateCounters($counters,$condition='',$params=array())
{
Yii::trace(get_class($this).'.updateCounters()','system.db.ar.CActiveRecord');
$builder=$this->getCommandBuilder();
$criteria=$builder->createCriteria($condition,$params);
$command=$builder->createUpdateCounterCommand($this->getTableSchema(),$counters,$criteria);
return $command->execute();
}
Updates one or several counter columns. Note, this updates all rows of data unless a condition or criteria is specified. See find() for detailed explanation about $condition and $params.
See Also
with() method
public static with() | ||
{return} | static | the AR object itself. |
public function with()
{
if(func_num_args()>0)
{
$with=func_get_args();
if(is_array($with[0])) // the parameter is given as an array
$with=$with[0];
if(!empty($with))
$this->getDbCriteria()->mergeWith(array('with'=>$with));
}
return $this;
}
Specifies which related objects should be eagerly loaded. This method takes variable number of parameters. Each parameter specifies the name of a relation or child-relation. For example,
// find all posts together with their author and comments Post::model()->with('author','comments')->findAll(); // find all posts together with their author and the author's profile Post::model()->with('author','author.profile')->findAll();The relations should be declared in relations().
By default, the options specified in relations() will be used to do relational query. In order to customize the options on the fly, we should pass an array parameter to the with() method. The array keys are relation names, and the array values are the corresponding query options. For example,
Post::model()->with(array( 'author'=>array('select'=>'id, name'), 'comments'=>array('condition'=>'approved=1', 'order'=>'create_time'), ))->findAll();
© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc/api/1.1/CActiveRecord