Methods summary
public
|
#
__construct( string $scenario = 'insert' )
Constructor.
Parameters
- $scenario
string
$scenario scenario name. See CModel::scenario for more details about
this parameter. Note: in order to setup initial model parameters use CActiveRecord::init() or CModel::afterConstruct(). Do NOT override the constructor unless it
is absolutely necessary!
|
public
|
#
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.)
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.)
|
public
static
|
#
cache( integer $duration, CCacheDependency|ICacheDependency $dependency = null, integer $queryCount = 1 )
Sets the parameters about query caching. This is a shortcut method to CDbConnection::cache(). It changes the query caching parameter of the dbConnection instance.
Sets the parameters about query caching. This is a shortcut method to CDbConnection::cache(). It changes the query caching parameter of the dbConnection instance.
Parameters
- $duration
integer
$duration the number of seconds that query results may remain valid in cache. If
this is 0, the caching will be disabled.- $dependency
CCacheDependency|ICacheDependency
$dependency the dependency that will be used when saving the query results into
cache.- $queryCount
integer
$queryCount 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. Returns
static
the active record instance itself.
Since
1.1.7
|
public
array
|
#
__sleep( )
PHP sleep magic method. This method ensures that the model meta data
reference is set to null.
PHP sleep magic method. This method ensures that the model meta data
reference is set to null.
Returns
array
|
public
mixed
|
#
__get( string $name )
PHP getter magic method. This method is overridden so that AR attributes can
be accessed like properties.
PHP getter magic method. This method is overridden so that AR attributes can
be accessed like properties.
Parameters
- $name
string
$name property name Returns
mixed
property value
Throws
See
Overrides
|
public
mixed
|
#
__set( string $name, mixed $value )
PHP setter magic method. This method is overridden so that AR attributes can
be accessed like properties.
PHP setter magic method. This method is overridden so that AR attributes can
be accessed like properties.
Parameters
- $name
string
$name property name- $value
mixed
$value property value Returns
mixed
Throws
CExceptionif the property/event is not defined or the property is read only.
Overrides
|
public
boolean
|
#
__isset( string $name )
Checks if a property value is null. This method overrides the parent
implementation by checking if the named attribute is null or not.
Checks if a property value is null. This method overrides the parent
implementation by checking if the named attribute is null or not.
Parameters
- $name
string
$name the property name or the event name Returns
boolean
whether the property value is null
Overrides
|
public
mixed
|
#
__unset( string $name )
Sets a component property to be null. This method overrides the parent
implementation by clearing the specified attribute value.
Sets a component property to be null. This method overrides the parent
implementation by clearing the specified attribute value.
Parameters
- $name
string
$name the property name or the event name Returns
mixed
Throws
Overrides
|
public
mixed
|
#
__call( string $name, array $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.
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.
Parameters
- $name
string
$name the method name- $parameters
array
$parameters method parameters Returns
mixed
the method return value
Throws
CExceptionif current class and its behaviors do not have a method or closure with the
given name
Overrides
|
public
mixed
|
#
getRelated( string $name, boolean $refresh = false, mixed $params = array() )
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.
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.
Parameters
- $name
string
$name the relation name (see CActiveRecord::relations())- $refresh
boolean
$refresh 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
$params 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. Returns
mixed
the related object(s).
Throws
|
public
boolean
|
#
hasRelated( string $name )
Returns a value indicating whether the named related object(s) has been
loaded.
Returns a value indicating whether the named related object(s) has been
loaded.
Parameters
- $name
string
$name the relation name Returns
boolean
a value indicating whether the named related object(s) has been loaded.
|
public
CDbCriteria
|
#
getDbCriteria( boolean $createIfNull = true )
Returns the query criteria associated with this model.
Returns the query criteria associated with this model.
Parameters
- $createIfNull
boolean
$createIfNull whether to create a criteria instance if it does not exist.
Defaults to true. Returns
CDbCriteriathe query criteria that is associated with this model. This criteria is mainly
used by scopes named scope feature to accumulate different criteria
specifications.
|
public
|
#
setDbCriteria( CDbCriteria $criteria )
Sets the query criteria for the current model.
Sets the query criteria for the current model.
Parameters
Since
1.1.3
|
public
array
|
#
defaultScope( )
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).
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).
Returns
arraythe query criteria. This will be used as the parameter to the constructor of
CDbCriteria.
|
public
static
|
#
resetScope( boolean $resetDefault = true )
Resets all scopes and criterias applied.
Resets all scopes and criterias applied.
Parameters
- $resetDefault
boolean
$resetDefault including default scope. This parameter available since 1.1.12 Returns
static
the AR instance itself
Since
1.1.2
|
public static
static
|
#
model( string $className = __CLASS__ )
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.)
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);
}
Parameters
- $className
string
$className active record class name. Returns
static
active record model instance.
|
public
CActiveRecordMetaData
|
#
getMetaData( )
Returns the meta-data for this AR
Returns the meta-data for this AR
Returns
|
public
|
#
refreshMetaData( )
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.
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.
|
public
string
|
#
tableName( )
Returns the name of the associated database table. By default this method
returns the class name as the table name. You may override this method if the
table is not named after this convention.
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.
Returns
string
the table name
|
public
mixed
|
#
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.
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.
Returns
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.
|
public
array
|
#
relations( )
This method should be overridden to declare related objects.
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'),
);
Returns
array
list of related object declarations. Defaults to empty array.
|
public
array
|
#
scopes( )
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.
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.
Returns
arraythe scope definition. The array keys are scope names; the array values are the
corresponding scope definitions. Each scope definition is represented as an
array whose keys must be properties of CDbCriteria.
|
public
array
|
#
attributeNames( )
Returns the list of all attribute names of the model. This would return all
column names of the table associated with this AR class.
Returns the list of all attribute names of the model. This would return all
column names of the table associated with this AR class.
Returns
array
list of attribute names.
|
public
string
|
#
getAttributeLabel( string $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.
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.
Parameters
- $attribute
string
$attribute the attribute name Returns
string
the attribute label
Since
1.1.4
See
Overrides
|
public
CDbConnection
|
#
getDbConnection( )
Returns the database connection used by active record. By default, the "db"
application component is used as the database connection. You may override this
method if you want to use a different database connection.
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.
Returns
Throws
|
public
CActiveRelation
|
#
getActiveRelation( string $name )
Returns the named relation declared for this AR class.
Returns the named relation declared for this AR class.
Parameters
- $name
string
$name the relation name Returns
CActiveRelationthe named relation declared for this AR class. Null if the relation does not
exist.
|
public
CDbTableSchema
|
#
getTableSchema( )
Returns the metadata of the table that this AR belongs to
Returns the metadata of the table that this AR belongs to
Returns
|
public
CDbCommandBuilder
|
#
getCommandBuilder( )
Returns the command builder used by this AR.
Returns the command builder used by this AR.
Returns
|
public
boolean
|
#
hasAttribute( string $name )
Checks whether this AR has the named attribute
Checks whether this AR has the named attribute
Parameters
- $name
string
$name attribute name Returns
boolean
whether this AR has the named attribute (table column).
|
public
mixed
|
#
getAttribute( string $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.
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.
Parameters
- $name
string
$name the attribute name Returns
mixed
the attribute value. Null if the attribute is not set or does not exist.
See
|
public
boolean
|
#
setAttribute( string $name, mixed $value )
Sets the named attribute value. You may also use $this->AttributeName to
set the attribute value.
Sets the named attribute value. You may also use $this->AttributeName to
set the attribute value.
Parameters
- $name
string
$name the attribute name- $value
mixed
$value the attribute value. Returns
boolean
whether the attribute exists and the assignment is conducted successfully
See
|
public
|
#
addRelatedRecord( string $name, mixed $record, mixed $index )
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.
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.
Parameters
- $name
string
$name attribute name- $record
mixed
$record the related record- $index
mixed
$index the index value in the related object collection. If true, it means using
zero-based integer index. If false, it means a HAS_ONE or BELONGS_TO object and
no index is needed.
|
public
array
|
#
getAttributes( mixed $names = true )
Returns all column attribute values. Note, related objects are not
returned.
Returns all column attribute values. Note, related objects are not
returned.
Parameters
- $names
mixed
$names 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. Returns
array
attribute values indexed by attribute names.
Overrides
|
public
boolean
|
#
save( boolean $runValidation = true, array $attributes = null )
Saves the current record.
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 CModel::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.
Parameters
- $runValidation
boolean
$runValidation whether to perform validation before saving the record. If the
validation fails, the record will not be saved to database.- $attributes
array
$attributes list of attributes that need to be saved. Defaults to null, meaning
all attributes that are loaded from DB will be saved. Returns
boolean
whether the saving succeeds
|
public
boolean
|
#
getIsNewRecord( )
Returns if the current record is new.
Returns if the current record is new.
Returns
booleanwhether the record is new and should be inserted when calling CActiveRecord::save(). This
property is automatically set in constructor and CActiveRecord::populateRecord().
Defaults to false, but it will be set to true if the instance is created using
the new operator.
|
public
|
#
setIsNewRecord( boolean $value )
Sets if the record is new.
Sets if the record is new.
Parameters
- $value
boolean
$value whether the record is new and should be inserted when calling CActiveRecord::save(). See
|
public
|
|
public
|
#
onAfterSave( CEvent $event )
This event is raised after the record is saved.
This event is raised after the record is saved.
Parameters
- $event
CEvent
$event the event parameter
|
public
|
|
public
|
#
onAfterDelete( CEvent $event )
This event is raised after the record is deleted.
This event is raised after the record is deleted.
Parameters
- $event
CEvent
$event the event parameter
|
public
|
#
onBeforeFind( CModelEvent $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 CActiveRecord::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 CActiveRecord::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.
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 CActiveRecord::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 CActiveRecord::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.
Parameters
See
|
public
|
#
onAfterFind( CEvent $event )
This event is raised after the record is instantiated by a find method.
This event is raised after the record is instantiated by a find method.
Parameters
- $event
CEvent
$event the event parameter
|
public
CActiveFinder
|
#
getActiveFinder( mixed $with )
Given 'with' options returns a new active finder instance.
Given 'with' options returns a new active finder instance.
Parameters
- $with
mixed
$with the relation names to be actively looked for Returns
Since
1.1.14
|
public
|
#
onBeforeCount( CModelEvent $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
CActiveRecord::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 CActiveRecord::getTableAlias() to get the alias used for the upcoming count call.
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
CActiveRecord::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 CActiveRecord::getTableAlias() to get the alias used for the upcoming count call.
Parameters
Since
1.1.14
See
|
protected
boolean
|
#
beforeSave( )
This method is invoked before saving a record (after validation, if any). The
default implementation raises the CActiveRecord::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.
This method is invoked before saving a record (after validation, if any). The
default implementation raises the CActiveRecord::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.
Returns
boolean
whether the saving should be executed. Defaults to true.
|
protected
|
#
afterSave( )
This method is invoked after saving a record successfully. The default
implementation raises the CActiveRecord::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.
This method is invoked after saving a record successfully. The default
implementation raises the CActiveRecord::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.
|
protected
boolean
|
#
beforeDelete( )
This method is invoked before deleting a record. The default implementation
raises the CActiveRecord::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.
This method is invoked before deleting a record. The default implementation
raises the CActiveRecord::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.
Returns
boolean
whether the record should be deleted. Defaults to true.
|
protected
|
#
afterDelete( )
This method is invoked after deleting a record. The default implementation
raises the CActiveRecord::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.
This method is invoked after deleting a record. The default implementation
raises the CActiveRecord::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.
|
protected
|
|
protected
|
|
protected
|
#
afterFind( )
This method is invoked after each record is instantiated by a find method.
The default implementation raises the CActiveRecord::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.
This method is invoked after each record is instantiated by a find method.
The default implementation raises the CActiveRecord::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.
|
public
|
|
public
|
|
public
boolean
|
#
insert( array $attributes = null )
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 CModel::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'.
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 CModel::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'.
Parameters
- $attributes
array
$attributes list of attributes that need to be saved. Defaults to null, meaning
all attributes that are loaded from DB will be saved. Returns
boolean
whether the attributes are valid and the record is inserted successfully.
Throws
|
public
boolean
|
#
update( array $attributes = null )
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 CModel::validate() to perform the validation.
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 CModel::validate() to perform the validation.
Parameters
- $attributes
array
$attributes list of attributes that need to be saved. Defaults to null, meaning
all attributes that are loaded from DB will be saved. Returns
boolean
whether the update is successful
Throws
|
public
boolean
|
#
saveAttributes( array $attributes )
Saves a selected list of attributes. Unlike CActiveRecord::save(), this method only
saves the specified attributes of an existing row dataset and does NOT call
either CActiveRecord::beforeSave() or CActiveRecord::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();
Saves a selected list of attributes. Unlike CActiveRecord::save(), this method only
saves the specified attributes of an existing row dataset and does NOT call
either CActiveRecord::beforeSave() or CActiveRecord::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();
Parameters
- $attributes
array
$attributes 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. Returns
boolean
whether the update is successful. Note that false is also returned if the saving
was successfull but no attributes had changed and the database driver returns 0
for the number of updated records.
Throws
|
public
boolean
|
#
saveCounters( array $counters )
Saves one or several counter columns for the current AR object. Note that
this method differs from CActiveRecord::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.
Saves one or several counter columns for the current AR object. Note that
this method differs from CActiveRecord::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.
Parameters
- $counters
array
$counters the counters to be updated (column name=>increment value) Returns
boolean
whether the saving is successful
Since
1.1.8
See
|
public
boolean
|
#
delete( )
Deletes the row corresponding to this active record.
Deletes the row corresponding to this active record.
Returns
boolean
whether the deletion is successful.
Throws
|
public
boolean
|
#
refresh( )
Repopulates this active record with the latest data.
Repopulates this active record with the latest data.
Returns
boolean
whether the row still exists in the database. If true, the latest data will be
populated to this active record.
|
public
boolean
|
#
equals( CActiveRecord $record )
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.
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.
Parameters
Returns
boolean
whether the two active records refer to the same row in the database table.
|
public
mixed
|
#
getPrimaryKey( )
Returns the primary key value.
Returns the primary key value.
Returns
mixed
the primary key value. An array (column name=>column value) is returned if
the primary key is composite. If primary key is not defined, null will be
returned.
|
public
|
#
setPrimaryKey( mixed $value )
Sets the primary key value. After calling this method, the old primary key
value can be obtained from oldPrimaryKey.
Sets the primary key value. After calling this method, the old primary key
value can be obtained from oldPrimaryKey.
Parameters
- $value
mixed
$value the new primary key value. If the primary key is composite, the new value
should be provided as an array (column name=>column value). Since
1.1.0
|
public
mixed
|
#
getOldPrimaryKey( )
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.
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.
Returns
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.
Since
1.1.0
|
public
|
#
setOldPrimaryKey( mixed $value )
Sets the old primary key value.
Sets the old primary key value.
Parameters
- $value
mixed
$value the old primary key value. Since
1.1.3
|
protected
mixed
|
#
query( CDbCriteria $criteria, boolean $all = false )
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.
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.
Parameters
- $criteria
CDbCriteria
$criteria the query criteria- $all
boolean
$all whether to return all data Returns
mixed
the AR objects populated with the query result
Since
1.1.7
|
public
|
#
applyScopes( CDbCriteria & $criteria )
Applies the query scopes to the given criteria. This method merges dbCriteria with the given criteria parameter. It then resets dbCriteria
to be null.
Applies the query scopes to the given criteria. This method merges dbCriteria with the given criteria parameter. It then resets dbCriteria
to be null.
Parameters
- $criteria
CDbCriteria
$criteria the query criteria. This parameter may be modified by merging dbCriteria.
|
public
string
|
#
getTableAlias( boolean $quote = false, boolean $checkScopes = true )
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 CActiveRecord::setTableAlias()
may be overridden by the applied scopes.
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 CActiveRecord::setTableAlias()
may be overridden by the applied scopes.
Parameters
- $quote
boolean
$quote whether to quote the alias name- $checkScopes
boolean
$checkScopes 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 CActiveRecord::defaultScope(). An infinite loop would be formed otherwise. Returns
string
the default table alias
Since
1.1.1
|
public
|
#
setTableAlias( string $alias )
Sets the table alias to be used in queries.
Sets the table alias to be used in queries.
Parameters
- $alias
string
$alias the table alias to be used in queries. The alias should NOT be quoted. Since
1.1.3
|
public
static
|
#
find( mixed $condition = '', array $params = array() )
Finds a single active record with the specified condition.
Finds a single active record with the specified condition.
Parameters
- $condition
mixed
$condition 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
$params 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. Returns
static
the record found. Null if no record is found.
|
public
static[]
|
#
findAll( mixed $condition = '', array $params = array() )
Finds all active records satisfying the specified condition. See CActiveRecord::find() for detailed explanation about $condition and $params.
Finds all active records satisfying the specified condition. See CActiveRecord::find() for detailed explanation about $condition and $params.
Parameters
- $condition
mixed
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
static[]
list of active records satisfying the specified condition. An empty array is
returned if none is found.
|
public
static
|
#
findByPk( mixed $pk, mixed $condition = '', array $params = array() )
Finds a single active record with the specified primary key. See CActiveRecord::find() for detailed explanation about $condition and $params.
Finds a single active record with the specified primary key. See CActiveRecord::find() for detailed explanation about $condition and $params.
Parameters
- $pk
mixed
$pk 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
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
static
the record found. Null if none is found.
|
public
static[]
|
#
findAllByPk( mixed $pk, mixed $condition = '', array $params = array() )
Finds all active records with the specified primary keys. See CActiveRecord::find()
for detailed explanation about $condition and $params.
Finds all active records with the specified primary keys. See CActiveRecord::find()
for detailed explanation about $condition and $params.
Parameters
- $pk
mixed
$pk 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
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
static[]
the records found. An empty array is returned if none is found.
|
public
static
|
#
findByAttributes( array $attributes, mixed $condition = '', array $params = array() )
Finds a single active record that has the specified attribute values. See
CActiveRecord::find() for detailed explanation about $condition and $params.
Finds a single active record that has the specified attribute values. See
CActiveRecord::find() for detailed explanation about $condition and $params.
Parameters
- $attributes
array
$attributes 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
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
static
the record found. Null if none is found.
|
public
static[]
|
#
findAllByAttributes( array $attributes, mixed $condition = '', array $params = array() )
Finds all active records that have the specified attribute values. See CActiveRecord::find() for detailed explanation about $condition and $params.
Finds all active records that have the specified attribute values. See CActiveRecord::find() for detailed explanation about $condition and $params.
Parameters
- $attributes
array
$attributes 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
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
static[]
the records found. An empty array is returned if none is found.
|
public
static
|
#
findBySql( string $sql, array $params = array() )
Finds a single active record with the specified SQL statement.
Finds a single active record with the specified SQL statement.
Parameters
- $sql
string
$sql the SQL statement- $params
array
$params parameters to be bound to the SQL statement Returns
static
the record found. Null if none is found.
|
public
static[]
|
#
findAllBySql( string $sql, array $params = array() )
Finds all active records using the specified SQL statement.
Finds all active records using the specified SQL statement.
Parameters
- $sql
string
$sql the SQL statement- $params
array
$params parameters to be bound to the SQL statement Returns
static[]
the records found. An empty array is returned if none is found.
|
public
string
|
#
count( mixed $condition = '', array $params = array() )
Finds the number of rows satisfying the specified query condition. See CActiveRecord::find() for detailed explanation about $condition and $params.
Finds the number of rows satisfying the specified query condition. See CActiveRecord::find() for detailed explanation about $condition and $params.
Parameters
- $condition
mixed
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
string
the number of rows satisfying the specified query condition. Note: type is
string to keep max. precision.
|
public
string
|
#
countByAttributes( array $attributes, mixed $condition = '', array $params = array() )
Finds the number of rows that have the specified attribute values. See CActiveRecord::find() for detailed explanation about $condition and $params.
Finds the number of rows that have the specified attribute values. See CActiveRecord::find() for detailed explanation about $condition and $params.
Parameters
- $attributes
array
$attributes 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
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
string
the number of rows satisfying the specified query condition. Note: type is
string to keep max. precision.
Since
1.1.4
|
public
string
|
#
countBySql( string $sql, array $params = array() )
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.
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.
Parameters
- $sql
string
$sql the SQL statement- $params
array
$params parameters to be bound to the SQL statement Returns
string
the number of rows using the given SQL statement. Note: type is string to keep
max. precision.
|
public
boolean
|
#
exists( mixed $condition = '', array $params = array() )
Checks whether there is row satisfying the specified condition. See CActiveRecord::find() for detailed explanation about $condition and $params.
Checks whether there is row satisfying the specified condition. See CActiveRecord::find() for detailed explanation about $condition and $params.
Parameters
- $condition
mixed
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
boolean
whether there is row satisfying the specified condition.
|
public
static
|
#
with( )
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 CActiveRecord::relations().
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 CActiveRecord::relations().
By default, the options specified in CActiveRecord::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();
Returns
static
the AR object itself.
|
public
static
|
|
public
integer
|
#
updateByPk( mixed $pk, array $attributes, mixed $condition = '', array $params = array() )
Updates records with the specified primary key(s). See CActiveRecord::find() for
detailed explanation about $condition and $params. Note, the attributes are not
checked for safety and validation is NOT performed.
Updates records with the specified primary key(s). See CActiveRecord::find() for
detailed explanation about $condition and $params. Note, the attributes are not
checked for safety and validation is NOT performed.
Parameters
- $pk
mixed
$pk 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
$attributes list of attributes (name=>$value) to be updated- $condition
mixed
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
integer
the number of rows being updated
|
public
integer
|
#
updateAll( array $attributes, mixed $condition = '', array $params = array() )
Updates records with the specified condition. See CActiveRecord::find() for detailed
explanation about $condition and $params. Note, the attributes are not checked
for safety and no validation is done.
Updates records with the specified condition. See CActiveRecord::find() for detailed
explanation about $condition and $params. Note, the attributes are not checked
for safety and no validation is done.
Parameters
- $attributes
array
$attributes list of attributes (name=>$value) to be updated- $condition
mixed
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
integer
the number of rows being updated
|
public
integer
|
#
updateCounters( array $counters, mixed $condition = '', array $params = array() )
Updates one or several counter columns. Note, this updates all rows of data
unless a condition or criteria is specified. See CActiveRecord::find() for detailed
explanation about $condition and $params.
Updates one or several counter columns. Note, this updates all rows of data
unless a condition or criteria is specified. See CActiveRecord::find() for detailed
explanation about $condition and $params.
Parameters
- $counters
array
$counters the counters to be updated (column name=>increment value)- $condition
mixed
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
integer
the number of rows being updated
See
|
public
integer
|
#
deleteByPk( mixed $pk, mixed $condition = '', array $params = array() )
Deletes rows with the specified primary key. See CActiveRecord::find() for detailed
explanation about $condition and $params.
Deletes rows with the specified primary key. See CActiveRecord::find() for detailed
explanation about $condition and $params.
Parameters
- $pk
mixed
$pk 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
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
integer
the number of rows deleted
|
public
integer
|
#
deleteAll( mixed $condition = '', array $params = array() )
Deletes rows with the specified condition. See CActiveRecord::find() for detailed
explanation about $condition and $params.
Deletes rows with the specified condition. See CActiveRecord::find() for detailed
explanation about $condition and $params.
Parameters
- $condition
mixed
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
integer
the number of rows deleted
|
public
integer
|
#
deleteAllByAttributes( array $attributes, mixed $condition = '', array $params = array() )
Deletes rows which match the specified attribute values. See CActiveRecord::find()
for detailed explanation about $condition and $params.
Deletes rows which match the specified attribute values. See CActiveRecord::find()
for detailed explanation about $condition and $params.
Parameters
- $attributes
array
$attributes 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
$condition query condition or criteria.- $params
array
$params parameters to be bound to an SQL statement. Returns
integer
number of rows affected by the execution.
|
public
static
|
#
populateRecord( array $attributes, boolean $callAfterFind = true )
Creates an active record with the given attributes. This method is internally
used by the find methods.
Creates an active record with the given attributes. This method is internally
used by the find methods.
Parameters
- $attributes
array
$attributes attribute values (column name=>column value)- $callAfterFind
boolean
$callAfterFind whether to call CActiveRecord::afterFind() after the record is populated. Returns
static
the newly created active record. The class of the object is the same as the
model class. Null is returned if the input data is false.
|
public
static[]
|
#
populateRecords( array $data, boolean $callAfterFind = true, string $index = null )
Creates a list of active records based on the input data. This method is
internally used by the find methods.
Creates a list of active records based on the input data. This method is
internally used by the find methods.
Parameters
- $data
array
$data list of attribute values for the active records.- $callAfterFind
boolean
$callAfterFind whether to call CActiveRecord::afterFind() after each record is populated.- $index
string
$index 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. Returns
static[]
list of active records.
|
protected
static
|
#
instantiate( array $attributes )
Creates an active record instance. This method is called by CActiveRecord::populateRecord() and CActiveRecord::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.
Creates an active record instance. This method is called by CActiveRecord::populateRecord() and CActiveRecord::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.
Parameters
- $attributes
array
$attributes list of attribute values for the active records. Returns
static
the active record
|
public
boolean
|
#
offsetExists( mixed $offset )
Returns whether there is an element at the specified offset. This method is
required by the interface ArrayAccess.
Returns whether there is an element at the specified offset. This method is
required by the interface ArrayAccess.
Parameters
- $offset
mixed
$offset the offset to check on Returns
boolean
Overrides
|
CModel
implements
IteratorAggregate,
ArrayAccess