Versions
Look up a class, method, property or event

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
CActiveRecord is the base class for classes representing relational data.

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

Hide inherited properties

PropertyTypeDescriptionDefined 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. 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

Hide inherited methods

MethodDescriptionDefined 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. 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

Hide inherited methods

MethodDescriptionDefined 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

Hide inherited events

EventDescriptionDefined 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

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

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.

metaData property read-only

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

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
Source Code: framework/db/ar/CActiveRecord.php#210 (show)
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!
Source Code: framework/db/ar/CActiveRecord.php#72 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#134 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#172 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#154 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#122 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#192 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#727 (show)
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()
Source Code: framework/db/ar/CActiveRecord.php#986 (show)
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()
Source Code: framework/db/ar/CActiveRecord.php#1031 (show)
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()
Source Code: framework/db/ar/CActiveRecord.php#1050 (show)
public function afterFindInternal()
{
    
$this->afterFind();
}

Calls afterFind. This method is internally used.

afterSave() method
protected void afterSave()
Source Code: framework/db/ar/CActiveRecord.php#955 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#1366 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#581 (show)
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()
Source Code: framework/db/ar/CActiveRecord.php#1019 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#968 (show)
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()
Source Code: framework/db/ar/CActiveRecord.php#1002 (show)
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()
Source Code: framework/db/ar/CActiveRecord.php#1041 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#937 (show)
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 CActiveRecord 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} CActiveRecord the active record instance itself.
Source Code: framework/db/ar/CActiveRecord.php#111 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#1592 (show)
public function count($condition='',$params=array())
{
    
Yii::trace(get_class($this).'.count()','system.db.ar.CActiveRecord');
    
$builder=$this->getCommandBuilder();
    
$this->beforeCount();
    
$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.
Source Code: framework/db/ar/CActiveRecord.php#1619 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#1645 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#351 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#1215 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#1812 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#1830 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#1796 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#1263 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#1659 (show)
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(falsefalse))->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 CActiveRecord 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} CActiveRecord the record found. Null if no record is found.
Source Code: framework/db/ar/CActiveRecord.php#1452 (show)
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 CActiveRecord[] findAll(mixed $condition='', array $params=array ( ))
$condition mixed query condition or criteria.
$params array parameters to be bound to an SQL statement.
{return} CActiveRecord[] list of active records satisfying the specified condition. An empty array is returned if none is found.
Source Code: framework/db/ar/CActiveRecord.php#1466 (show)
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 CActiveRecord[] 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} CActiveRecord[] the records found. An empty array is returned if none is found.
Source Code: framework/db/ar/CActiveRecord.php#1531 (show)
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 CActiveRecord[] 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} CActiveRecord[] the records found. An empty array is returned if none is found.
Source Code: framework/db/ar/CActiveRecord.php#1497 (show)
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 CActiveRecord[] findAllBySql(string $sql, array $params=array ( ))
$sql string the SQL statement
$params array parameters to be bound to the SQL statement
{return} CActiveRecord[] the records found. An empty array is returned if none is found.
Source Code: framework/db/ar/CActiveRecord.php#1568 (show)
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 CActiveRecord 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} CActiveRecord the record found. Null if none is found.
Source Code: framework/db/ar/CActiveRecord.php#1514 (show)
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 CActiveRecord 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} CActiveRecord the record found. Null if none is found.
Source Code: framework/db/ar/CActiveRecord.php#1481 (show)
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 CActiveRecord findBySql(string $sql, array $params=array ( ))
$sql string the SQL statement
$params array parameters to be bound to the SQL statement
{return} CActiveRecord the record found. Null if none is found.
Source Code: framework/db/ar/CActiveRecord.php#1545 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#907 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#647 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#691 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#597 (show)
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.

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.
Source Code: framework/db/ar/CActiveRecord.php#754 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#665 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#628 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#323 (show)
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. Defaults to false, but it will be set to true if the instance is created using the new operator.
Source Code: framework/db/ar/CActiveRecord.php#818 (show)
public function getIsNewRecord()
{
    return 
$this->_new;
}

Returns if the current record is new.

getMetaData() method
public CActiveRecordMetaData getMetaData()
{return} CActiveRecordMetaData the meta for this AR class.
Source Code: framework/db/ar/CActiveRecord.php#405 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#1318 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#1273 (show)
public function getPrimaryKey()
{
    
$table=$this->getMetaData()->tableSchema;
    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).
Source Code: framework/db/ar/CActiveRecord.php#250 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#1422 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#656 (show)
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).
Source Code: framework/db/ar/CActiveRecord.php#675 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#311 (show)
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()
Source Code: framework/db/ar/CActiveRecord.php#94 (show)
public function 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.
Source Code: framework/db/ar/CActiveRecord.php#1067 (show)
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->getMetaData()->tableSchema;
        
$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 CActiveRecord instantiate(array $attributes)
$attributes array list of attribute values for the active records.
{return} CActiveRecord the active record
Source Code: framework/db/ar/CActiveRecord.php#1908 (show)
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 CActiveRecord model(string $className='CActiveRecord')
$className string active record class name.
{return} CActiveRecord active record model instance.
Source Code: framework/db/ar/CActiveRecord.php#389 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#1921 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#866 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#894 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#847 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#923 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#857 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#885 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#838 (show)
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 CActiveRecord 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} CActiveRecord 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.
Source Code: framework/db/ar/CActiveRecord.php#1848 (show)
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 CActiveRecord[] 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} CActiveRecord[] list of active records.
Source Code: framework/db/ar/CActiveRecord.php#1882 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#452 (show)
public function primaryKey()
{
}

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
Source Code: framework/db/ar/CActiveRecord.php#1341 (show)
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,$this->getTableAlias());
        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.
Source Code: framework/db/ar/CActiveRecord.php#1237 (show)
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()
Source Code: framework/db/ar/CActiveRecord.php#423 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#535 (show)
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 CActiveRecord resetScope(boolean $resetDefault=true)
$resetDefault boolean including default scope. This parameter available since 1.1.12
{return} CActiveRecord
Source Code: framework/db/ar/CActiveRecord.php#363 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#803 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#1151 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#1193 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#571 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#707 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#338 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#828 (show)
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.
Source Code: framework/db/ar/CActiveRecord.php#1328 (show)
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).
Source Code: framework/db/ar/CActiveRecord.php#1296 (show)
public function setPrimaryKey($value)
{
    
$this->_pk=$this->getPrimaryKey();
    
$table=$this->getMetaData()->tableSchema;
    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.
Source Code: framework/db/ar/CActiveRecord.php#1436 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#436 (show)
public function tableName()
{
    return 
get_class($this);
}

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 CActiveRecord together()
{return} CActiveRecord the AR object itself
Source Code: framework/db/ar/CActiveRecord.php#1725 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#1115 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#1760 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#1741 (show)
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
Source Code: framework/db/ar/CActiveRecord.php#1779 (show)
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 CActiveRecord with()
{return} CActiveRecord the AR object itself.
Source Code: framework/db/ar/CActiveRecord.php#1705 (show)
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();

Total 10 comments

#13700 report it
PrplHaz4 at 2013/06/18 10:08am
Using with() to specify table aliases for multiple joins to same table/relation name

I ran into a situation where I had multiple joins to the same table, and needed to create an alias to disambiguate. An example of this would be using multiple joins to a user table to get created_by and updated_by user names.

'with' => array(
  'creator',  //comment creator (which is a User)
  'post.creator' => array('alias' => 'creator_user'), // (also User)
  'post.updater' => array('alias' => 'updater_user'), // (another User)
),
'together' => true,
#12508 report it
toph at 2013/03/25 03:54am
Relations from database views

In order to use relations in models created from database views the primaryKey() method must be overwritten to explicitly state the primary key field(s).

#11293 report it
SteveD at 2013/01/03 08:41pm
defaultScope() can return a CDbCriteria object

This seems to be undocumented. The description on this page says the value returned by defaultScope() "will be used as the parameter to the constructor of CDbCriteria." However, you can also construct a CDbCriteria object and simply return the object. This gives much more flexibility in criteria logic compared to just returning a parameter list for the constructor.

#11288 report it
SteveD at 2013/01/03 02:35pm
Using 'with' for related table in defaultScope()

This is the syntax for defining a defaultScope based on a condition in a related table:

public function defaultScope()
{
   return array(
      'with'=>array(
         'relationName'=>array('condition'=>'columnNameInRelatedTable=' . $someValue),
      ),
   );  
}
#9635 report it
SteveD at 2012/08/30 09:44pm
Cancelling save in the model

The following wasn't obvious to me from the documentation, so I'm mentioning it in case it will help someone else.

In order to prevent a model from saving the current active record when the model's save method is called, add a public function beforeSave() to the model. You can perform any tests you like in the function. The function must return true or else the save operation will be cancelled.

I expect that the same logic applies to beforeDelete, but I haven't tested it.

#4228 report it
pligor at 2011/06/17 05:24am
Display insert method usage using csv data

This is the body of a method to show usage of the insert method. It loads data from a stored csv file

$model = new ClassNameOfModel();
$model->deleteAll();    //delete ALL rows
 
$csvPath = Yii::app()->getBasePath() . "/data/". $model->tableName(). ".csv";
$fp = fopen($csvPath,'r');
 
$allInserted = true;
while( ( $row = fgetcsv($fp,0,';') )!== false )
{
    $model = new EidosParagogou();
    $model->id= $row[0];
    $model->eidos= $row[1];
    $insertion = $model->insert();
 
    $allInserted &= $insertion;
}       
return $allInserted;

(In case csv data are a lot, probably this is not the best code. A more efficient way is needed)

#4209 report it
jeremy at 2011/06/15 10:35pm
defaultScope() should not include 'order' if using CGridView

if you use CGridView, don't put 'order'=> in your defaultScope(). Otherwise, when the user clicks the column heading in the grid-view, it puts the column name in ORDER BY clause twice, yielding invalid SQL.

#3265 report it
Steve Friedl at 2011/03/30 10:28am
Behavior in afterSave()

In afterSave(), your code can distinguish between a just-inserted record and an updated one by examining the $this->isNewRecord attribute — Yii does not update this to false until after afterSave completes.

For models with autogenerated primary keys, the value of $this->id is available while afterSave is running.

#2225 report it
Steve Friedl at 2010/11/28 05:15pm
Format of getErrors() return

When actions like $model->save() fail, there are reasons provided in the getErrors() method, and it took a bit of digging to figure out how to decode them from a console-mode application.

The return is a hash of attribute names referencing arrays of strings, and this snippet displays them:

foreach ($model->getErrors() as $attrname => $errlist )
{
    echo "  Errorred attribute: $attrname\n";
    foreach ($errlist as $err)
    {
        echo "    $err\n";
    }
}
#1341 report it
mindplay at 2009/09/03 04:39pm
with() supports named scopes

Note that with() supports simple (non-parameterized) named scopes - for example, to select recent posts by active authors (assuming Post has a scope named recent, and Author has a scope named active), you can do this:

Post::model()->recent()->with('author:active')->findAll();

It is important to understand that once you call with(), you break the call-chain - you have left model-land and entered relational query land.

That is, you are no longer working with the static CActiveRecord instance returned by model(), but rather, any chained calls after with() are working on a CActiveFinder instance.

That is why you must always call with() after you have called any other scope-methods - the reason you can still call findAll() and other methods after with(), is that you are actually calling a different method, namely CActiveFinder::findAll(), rather than CActiveRecord::findAll() - while these have identical names and APIs, they are two different methods belonging to different objects.

Also note the limitation of named scopes using the with('x:y') syntax - this works only with simple scopes, defined using the scopes() callback method; it does not work with parameterized scopes defined by adding methods to your model.

Leave a comment

Please to leave your comment.