CActiveRecord
| 包 | system.db.ar |
|---|---|
| 继承 | abstract class CActiveRecord » CModel » CComponent |
| 实现 | ArrayAccess, Traversable, IteratorAggregate |
| 可用自 | 1.0 |
| 版本 | $Id$ |
CActiveRecord is the base class for classes representing relational data.
It implements the active record design pattern, a popular Object-Relational Mapping (ORM) technique.
Each active record class represents a database table/view, while an active record instance represents a row in that table. Using CActiveRecord, one can perform CRUD (create, read, update, delete) database actions in an object-oriented way. For example, the following code inserts a row to the 'Post' table (where 'Post' is the class representing the 'Post' table):
In the following, we elaborate how to use CActiveRecord.
First, we need to set up a database connection to be used by CActiveRecord. This is done by loading a CDbConnection application component whose ID is "db", using the following application configuration:
Second, for every database table that we want to access, define an active record class. The following example shows the minimal code needed for a 'Post' class, which represents the 'Post' table.
To access column values, use $record->columnName, where $record refers to an active record instance. For example, the following code sets the 'title' column (attribute) of $post:
To insert a new row into 'Post', we first create a new instance of 'Post' class, and then call 'save()' to do the insertion.
To query for posts, we will use the 'model' method we defined earlier on. The 'model' method is the only static method defined in CActiveRecord. It returns a static active record instance that is used to access class-level methods (something similar to static class methods). The following 'find' methods are all class-level methods that CActiveRecord implements to facilitate database querying:
As we can see from the above, we have a set of find() methods and a set of findAll() methods. The result of the former is either an active record instance or null if no result is found, while the result of the latter is always an array.
After obtaining an active record from query, we can update it or delete it.
CActiveRecord also has a few class-level methods to facilitate updating and deleting rows without instantiating active record objects. Below is a summary:
A very useful feature that CActiveRecord supports is retrieving related active records. An active record is often related with other active records, via the relationship defined between database tables. For example, a post belongs to an author and has many comments; a user has a profile; a post belongs to and has many categories. CActiveRecord makes retrieving these related objects very easy.
Before retrieving related objects, we need to declare these relations in the class definition. This is done by overriding the relations method:
Since the 'Post' class knows what kind of related objects it has, we can use the following code to access the author and comments of a post:
If we have 100 posts and would like to obtain the author and comments for every post, lazy loading would be very inefficient, because it means we will need 200 SQL queries in order to fetch those related objects. In this situation, we should resort to the so-called eager loading.
Eager loading can be nested. For example, if for every comment, we also want to know its author, we could use the following 'with' find:
There is a minor inconvenience when using eager loading, though. That is, we need to disambiguate any column references in conditions or search criteria, because we are joining several tables together. In general, it would be safe if we prefix every column referenced in the condition or search criteria with the table name.
Now let's describe more about the possible relations we can declare for active records. From database point of view, the relationship between two tables A and B has three types: one-to-many, one-to-one and many-to-many. In active records, these are classified into four types:
We already see how to declare a relation in an active record class. In many situations, we often have more constraints on those related objects, such as the conditions that the related objects should satisfy, their orderings, etc. These can be specified as additional options in our relation declaration. For example,
Since version 1.0.4, a new relational query, called STAT, is supported. It is meant to perform relational queries that return statistical information about related objects (e.g. the number of comments that each post has). To use this new relational query, we need to declare it in the relations method like other relations:
CActiveRecord has built-in validation functionality that validates the user input data before they are saved to database. To use the validation, override CModel::rules() as follows,
When save is called, validation will be performed. If there are any validation errors, save will return false and the errors can be retrieved back via getErrors.
It implements the active record design pattern, a popular Object-Relational Mapping (ORM) technique.
Each active record class represents a database table/view, while an active record instance represents a row in that table. Using CActiveRecord, one can perform CRUD (create, read, update, delete) database actions in an object-oriented way. For example, the following code inserts a row to the 'Post' table (where 'Post' is the class representing the 'Post' table):
$post=new Post; $post->title='sample post'; $post->save();
In the following, we elaborate how to use CActiveRecord.
First, we need to set up a database connection to be used by CActiveRecord. This is done by loading a CDbConnection application component whose ID is "db", using the following application configuration:
array(
'components'=>array(
'db'=>array(
'class'=>'CDbConnection',
'connectionString'=>'sqlite:test.db',
),
)
);
To use a different database connection, you should override getDbConnection.
Second, for every database table that we want to access, define an active record class. The following example shows the minimal code needed for a 'Post' class, which represents the 'Post' table.
class Post extends CActiveRecord
{
public static function model($className=__CLASS__)
{
return parent::model($className);
}
}
The 'model()' method is declared as such for every active record class (to be explained shortly).
By convention, the 'Post' class is associated with the database table named 'Post' (the class name).
If the class should be associated with some other table, you may override
the tableName() method.
To access column values, use $record->columnName, where $record refers to an active record instance. For example, the following code sets the 'title' column (attribute) of $post:
$post=new Post; $post->title='a sample post';Although we never explicitly declare the 'title' property in the 'Post' class, we can still access it in the above code. This is because 'title' is a column in the 'Post' table, and CActiveRecord makes it accessible as a property with the help of PHP __get() magic method. If you attempt to access a non-existing column in the same way, an exception will be thrown.
To insert a new row into 'Post', we first create a new instance of 'Post' class, and then call 'save()' to do the insertion.
$post=new Post; $post->title='sample post'; $post->save();After insertion, the $post object will contain an updated primary key if it is auto-incremental.
To query for posts, we will use the 'model' method we defined earlier on. The 'model' method is the only static method defined in CActiveRecord. It returns a static active record instance that is used to access class-level methods (something similar to static class methods). The following 'find' methods are all class-level methods that CActiveRecord implements to facilitate database querying:
// find the first row satisfying the specified condition $post=Post::model()->find($condition,$params); // find all rows satisfying the specified condition $posts=Post::model()->findAll($condition,$params); // find the row with the specified primary key $post=Post::model()->findByPk($postID,$condition,$params); // find all rows with the specified primary keys $posts=Post::model()->findAllByPk($postIDs,$condition,$params); // find the row with the specified attribute values $post=Post::model()->findByAttributes($attributes,$condition,$params); // find all rows with the specified attribute values $posts=Post::model()->findAllByAttributes($attributes,$condition,$params); // find the first row using the specified SQL statement $post=Post::model()->findBySql($sql,$params); // find all rows using the specified SQL statement $posts=Post::model()->findAllBySql($sql,$params); // get the number of rows satisfying the specified condition $n=Post::model()->count($condition,$params); // get the number of rows using the specified SQL statement $n=Post::model()->countBySql($sql,$params);where $condition specifies the WHERE clause, and $params gives a list of parameters that should be bound to the generated SQL statement. You may also pass a CDbCriteria object at the place of $condition to specify more complex query conditions (in that case, $params will be ignored since you can sepcify it in the CDbCriteria object.)
As we can see from the above, we have a set of find() methods and a set of findAll() methods. The result of the former is either an active record instance or null if no result is found, while the result of the latter is always an array.
After obtaining an active record from query, we can update it or delete it.
$post->title='new post title'; $post->save(); // or $post->delete();In the above, we are using the same 'save()' method to do both insertion and update. CActiveRecord is intelligent enough to differentiate these two scenarios.
CActiveRecord also has a few class-level methods to facilitate updating and deleting rows without instantiating active record objects. Below is a summary:
// update all records with the specified attributes and condition Post::model()->updateAll($attributes,$condition,$params); // update one or several records with the specified primary key(s) and attribute values Post::model()->updateByPk($postID,$attributes,$condition,$params); // update one or several counter columns Post::model()->updateCounters($counters,$condition,$params); // delete one or several records with the specified primary key(s) and attribute values Post::model()->deleteByPk($pk,$condition,$params); // delete all records with the specified condition Post::model()->deleteAll($condition,$params); // delete all records which match the specified attribute values Post::model()->deleteAllByAttributes($condition,$params); // check if a record exists with the specified condition Post::model()->exists($condition,$params);
A very useful feature that CActiveRecord supports is retrieving related active records. An active record is often related with other active records, via the relationship defined between database tables. For example, a post belongs to an author and has many comments; a user has a profile; a post belongs to and has many categories. CActiveRecord makes retrieving these related objects very easy.
Before retrieving related objects, we need to declare these relations in the class definition. This is done by overriding the relations method:
class Post extends CActiveRecord
{
public function relations()
{
return array(
'author'=>array(self::BELONGS_TO, 'User', 'authorID'),
'comments'=>array(self::HAS_MANY, 'Comment', 'postID'),
);
}
}
In the above, we declare two relations:
- the 'author' relation is of BELONGS_TO type; it references the 'User' active record class; and the 'authorID' column of the 'Post' table is the foreign key.
- the 'comments' relation is of HAS_MANY type; it references the 'Comment' active record class; and the 'postID' column of the 'Comment' table is the foreign key.
Since the 'Post' class knows what kind of related objects it has, we can use the following code to access the author and comments of a post:
$post=Post::model()->findByPk($postID); $author=$post->author; $comments=$post->comments;Internally, when we access 'author' or 'comments' the first time, an SQL query will be executed to fetch the corresponding active record(s). This is the so-called lazy loading, i.e., the related objects are loaded the first time when they are accessed.
If we have 100 posts and would like to obtain the author and comments for every post, lazy loading would be very inefficient, because it means we will need 200 SQL queries in order to fetch those related objects. In this situation, we should resort to the so-called eager loading.
$posts=Post::model()->with('author','comments')->findAll($condition,$params);
Here we used the 'with' method to specify that we want to bring back post records
together with their related author and comments. Internally, two SQL queries
will be created and executed: one brings back the posts and their authors, and the other
brings back the comments). The reason we do not fetch them all together in one shot is
because the returned rows would otherwise contain many repetitive results (e.g. the post
information is repeated for every comment it has), which is both inefficient for database
server and PHP code.
Eager loading can be nested. For example, if for every comment, we also want to know its author, we could use the following 'with' find:
$posts=Post::model()->with(array('author','comments'=>'author'))->findAll($condition,$params);
How many SQL queries do we need now? Still two (one for posts and their authors, and one
for comments and their authors)! In fact, if there are N HAS_MANY/MANY_MANY relations involved,
we would need N+1 queries in total.
There is a minor inconvenience when using eager loading, though. That is, we need to disambiguate any column references in conditions or search criteria, because we are joining several tables together. In general, it would be safe if we prefix every column referenced in the condition or search criteria with the table name.
Now let's describe more about the possible relations we can declare for active records. From database point of view, the relationship between two tables A and B has three types: one-to-many, one-to-one and many-to-many. In active records, these are classified into four types:
- BELONGS_TO: if A vs. B is one-to-many, then B belongs to A (e.g. a post belongs to an author);
- HAS_MANY: if A vs. B is one-to-many, then A has many B (e.g. an author has many posts);
- HAS_ONE: this is special case of has-many where A has at most one B;
- MANY_MANY: this corresponds to many-to-many relationship in database. An intermediate join table is needed as most DBMS do not support many-to-many relationship directly. For example, a post can belong to many categories and a category can have many posts. We would use a table 'post_category' to join the 'posts' and 'categories' tables together.
We already see how to declare a relation in an active record class. In many situations, we often have more constraints on those related objects, such as the conditions that the related objects should satisfy, their orderings, etc. These can be specified as additional options in our relation declaration. For example,
class Post extends CActiveRecord
{
......
public function relations()
{
return array(
'comments'=>array(self::HAS_MANY,'Comment','postID',
'order'=>'??.createTime DESC',
'with'=>'author'),
);
}
}
where the 'order' option specifies that the comments should be sorted by their creation time,
and the 'with' option specifies that the comments should be loaded together with their authors.
The special token '??.' is for disamibiguating the column reference. When SQL statement
is generated, it will be replaced automatically by the table alias for the 'Comment' table.
More detailed description about possible options can be found in CActiveRelation and
CHasManyRelation.
Since version 1.0.4, a new relational query, called STAT, is supported. It is meant to perform relational queries that return statistical information about related objects (e.g. the number of comments that each post has). To use this new relational query, we need to declare it in the relations method like other relations:
class Post extends CActiveRecord
{
......
public function relations()
{
return array(
'commentCount'=>array(self::STAT,'Comment','postID'),
'comments'=>array(self::HAS_MANY,'Comment','postID',
'order'=>'??.createTime DESC',
'with'=>'author'),
);
}
}
In the above, we declare 'commentCount' to be a STAT relation that is related with
the Comment model via its foreign key postID. Given a post
model instance, we can then obtain the number of comments it has via the expression
$post->commentCount. We can also obtain the number of comments for a list
of posts via eager loading:
$posts=Post::model()->with('commentCount')->findAll();
CActiveRecord has built-in validation functionality that validates the user input data before they are saved to database. To use the validation, override CModel::rules() as follows,
class Post extends CActiveRecord
{
public function rules()
{
return array(
array('title, content', 'required'),
array('title', 'length', 'min'=>5),
);
}
}
The method returns a list of validation rules, each represented as an array of the following format:
array('attribute list', 'validator name', 'on'=>'insert', ...validation parameters...)
where
- attribute list: specifies the attributes to be validated;
- validator name: specifies the validator to be used. It can be a class name (or class in dot syntax),
or a validation method in the AR class. A validator class must extend from CValidator,
while a validation method must have the following signature:
function validatorName($attribute,$params)
When using a built-in validator class, you can use an alias name instead of the full class name. For example, you can use "required" instead of "system.validators.CRequiredValidator". For more details, see CValidator. - on: this specifies the scenario when the validation rule should be performed. Please see CModel::validate for more details about this option. NOTE: if the validation is triggered by the save call, it will use 'insert' to indicate an insertion operation, and 'update' an updating operation. You may thus specify a rule with the 'on' option so that it is applied only to insertion or updating.
- additional parameters are used to initialize the corresponding validator properties. See CValidator for possible properties.
When save is called, validation will be performed. If there are any validation errors, save will return false and the errors can be retrieved back via getErrors.
公共属性
| 属性 | 类型 | 描述 | 被定义在 |
|---|---|---|---|
| attributes | array | Returns all column attribute values. | CActiveRecord |
| commandBuilder | CDbCommandBuilder | 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 | whether the record is new and should be inserted when calling save. | CActiveRecord |
| iterator | CMapIterator | Returns an iterator for traversing the attributes in the model. | CModel |
| metaData | CActiveRecordMetaData | the meta for this AR class. | CActiveRecord |
| primaryKey | mixed | 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 in. | CModel |
| tableSchema | CDbTableSchema | the metadata of the table that this AR belongs to | CActiveRecord |
| validators | array | Returns a list of validators created according to rules. | CActiveRecord |
公共方法
| 方法 | 描述 | 被定义在 |
|---|---|---|
| __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() | Adds a related object to this record. | 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 |
| 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 |
| countBySql() | Finds the number of rows using the given SQL statement. | CActiveRecord |
| createValidators() | 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 this active record with another one. | CActiveRecord |
| 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 |
| getActiveRelation() | CActiveRecord | |
| getAttribute() | Returns the named attribute value. | CActiveRecord |
| getAttributeLabel() | Returns the text label for the specified attribute. | CModel |
| getAttributes() | Returns all column attribute values. | CActiveRecord |
| getCommandBuilder() | 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() | CActiveRecord | |
| getIterator() | Returns an iterator for traversing the attributes in the model. | CModel |
| getMetaData() | CActiveRecord | |
| getPrimaryKey() | 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 in. | CModel |
| getTableSchema() | CActiveRecord | |
| getValidators() | Returns a list of validators created according to rules. | CActiveRecord |
| getValidatorsForAttribute() | Returns the validators that are applied to the specified attribute under the specified scenario. | CModel |
| hasAttribute() | 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 |
| 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 record instance is created by new operator. | CActiveRecord |
| 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 |
| 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 |
| 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 |
| rules() | Returns the validation rules for attributes. | CModel |
| safeAttributes() | Returns the name of attributes that are safe to be massively assigned. | CActiveRecord |
| save() | Saves the current record. | CActiveRecord |
| saveAttributes() | Saves a selected list of attributes. | 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 |
| setIsNewRecord() | CActiveRecord | |
| setScenario() | CModel | |
| tableName() | Returns the name of the associated database table. | CActiveRecord |
| 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 |
受保护的方法
| 方法 | 描述 | 被定义在 |
|---|---|---|
| afterConstruct() | This method is invoked after a record instance is created by new operator. | CActiveRecord |
| 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. | CActiveRecord |
| afterValidate() | This method is invoked after validation ends. | CModel |
| 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 |
事件
| 事件 | 描述 | 被定义在 |
|---|---|---|
| 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 |
| onAfterConstruct | This event is raised after the record instance is created by new operator. | 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 |
| onBeforeValidate | This event is raised before the validation is performed. | CModel |
| onAfterValidate | This event is raised after the validation is performed. | CModel |
属性详情
attributes
属性
public array getAttributes(mixed $names=true)
public void setAttributes(array $values, mixed $scenario='')
public void setAttributes(array $values, mixed $scenario='')
Returns all column attribute values. Note, related objects are not returned.
commandBuilder
属性
只读
public CDbCommandBuilder getCommandBuilder()
the command builder used by this AR
db
属性
public static CDbConnection $db;
the default database connection for all active record classes. By default, this is the 'db' application component.
dbConnection
属性
只读
public CDbConnection getDbConnection()
Returns the database connection used by active record. By default, the "db" application component is used as the database connection. You may override this method if you want to use a different database connection.
dbCriteria
属性
只读 （自版本 v1.0.5 可用）
public CDbCriteria getDbCriteria(boolean $createIfNull=true)
Returns the query criteria associated with this model.
isNewRecord
属性
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.
metaData
属性
只读
public CActiveRecordMetaData getMetaData()
the meta for this AR class.
primaryKey
属性
只读
public mixed getPrimaryKey()
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.
tableSchema
属性
只读
public CDbTableSchema getTableSchema()
the metadata of the table that this AR belongs to
validators
属性
只读 （自版本 v1.0.1 可用）
public array getValidators()
Returns a list of validators created according to rules. This overrides the parent implementation so that the validators are only created once for each type of AR.
方法详情
__call()
方法
（自版本 v1.0.5 可用）
|
public mixed __call(string $name, array $parameters)
| ||
| $name | string | the method name |
| $parameters | array | method parameters |
| {return} | mixed | the method return value |
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()
方法
|
public void __construct(array $attributes=array (
), string $scenario='')
| ||
| $attributes | array | initial attributes (name => value). The attributes are subject to filtering via setAttributes. If this parameter is null, nothing will be done in the constructor (this is internally used by populateRecord). |
| $scenario | string | scenario name. See setAttributes for more details about this parameter. This parameter has been available since version 1.0.2. As of version 1.0.4, this parameter will be used to set the scenario property of the model. |
Constructor.
__get()
方法
|
public mixed __get(string $name)
| ||
| $name | string | property name |
| {return} | mixed | property value |
PHP getter magic method. This method is overridden so that AR attributes can be accessed like properties.
参见
__isset()
方法
（自版本 v1.0.1 可用）
|
public boolean __isset(string $name)
| ||
| $name | string | the property name or the event name |
| {return} | boolean | whether the property value is null |
Checks if a property value is null. This method overrides the parent implementation by checking if the named attribute is null or not.
__set()
方法
|
public void __set(string $name, mixed $value)
| ||
| $name | string | property name |
| $value | mixed | property value |
PHP setter magic method. This method is overridden so that AR attributes can be accessed like properties.
__sleep()
方法
|
public void __sleep()
|
PHP sleep magic method. This method ensures that the model meta data reference is set to null.
__unset()
方法
（自版本 v1.0.1 可用）
|
public void __unset(string $name)
| ||
| $name | string | the property name or the event name |
Sets a component property to be null. This method overrides the parent implementation by clearing the specified attribute value.
addRelatedRecord()
方法
|
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. |
Adds a related object to this record. This method is used internally by CActiveFinder to populate related objects.
afterConstruct()
方法
|
protected void afterConstruct()
|
This method is invoked after a record instance is created by new operator. The default implementation raises the onAfterConstruct event. You may override this method to do postprocessing after record creation. Make sure you call the parent implementation so that the event is raised properly.
afterDelete()
方法
|
protected void afterDelete()
|
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()
方法
|
protected void afterFind()
|
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()
方法
（自版本 v1.0.3 可用）
|
public void afterFindInternal()
|
Calls afterFind. This method is internally used.
afterSave()
方法
|
protected void afterSave()
|
This method is invoked after saving a record. 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()
方法
（自版本 v1.0.12 可用）
|
public void applyScopes(CDbCriteria $criteria)
| ||
| $criteria | CDbCriteria | the query criteria. This parameter may be modified by merging dbCriteria. |
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()
方法
（自版本 v1.0.1 可用）
|
public array attributeNames()
| ||
| {return} | array | list of attribute names. |
Returns the list of all attribute names of the model. This would return all column names of the table associated with this AR class.
beforeDelete()
方法
|
protected boolean beforeDelete()
| ||
| {return} | boolean | whether the record should be deleted. Defaults to 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()
方法
（自版本 v1.0.9 可用）
|
protected void beforeFind()
|
This method is invoked before an AR finder executes a find call. The find calls include find, findAll, findByPk, findAllByPk, findByAttributes and findAllByAttributes. 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.
beforeFindInternal()
方法
（自版本 v1.0.11 可用）
|
public void beforeFindInternal()
|
Calls beforeFind. This method is internally used.
beforeSave()
方法
|
protected boolean beforeSave()
| ||
| {return} | boolean | whether the saving should be executed. Defaults to 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.
count()
方法
|
public integer count(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 satisfying the specified query condition. |
Finds the number of rows satisfying the specified query condition. See find() for detailed explanation about $condition and $params.
countBySql()
方法
|
public integer countBySql(string $sql, array $params=array (
))
| ||
| $sql | string | the SQL statement |
| $params | array | parameters to be bound to the SQL statement |
| {return} | integer | the number of rows using the given SQL statement. |
Finds the number of rows using the given SQL statement.
defaultScope()
方法
（自版本 v1.0.5 可用）
|
public array defaultScope()
| ||
| {return} | array | the query criteria. This will be used as the parameter to the constructor of CDbCriteria. |
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()
方法
|
public boolean delete()
| ||
| {return} | boolean | whether the deletion is successful. |
Deletes the row corresponding to this active record.
deleteAll()
方法
|
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 |
Deletes rows with the specified condition. See find() for detailed explanation about $condition and $params.
deleteAllByAttributes()
方法
（自版本 v1.0.9 可用）
|
public CActiveRecord deleteAllByAttributes(array $attributes, mixed $condition='', array $params=array (
))
| ||
| $attributes | array | list of attribute values (indexed by attribute names) that the active records should match. Since version 1.0.8, 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. |
Deletes rows which match the specified attribute values. See find() for detailed explanation about $condition and $params.
deleteByPk()
方法
|
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 |
Deletes rows with the specified primary key. See find() for detailed explanation about $condition and $params.
equals()
方法
|
public boolean equals($record)
| ||
| $record | ||
| {return} | boolean | whether the two active records refer to the same row in the database table. |
Compares this active record with another one. The comparison is made by comparing the primary key values of the two active records.
exists()
方法
|
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. |
Checks whether there is row satisfying the specified condition. See find() for detailed explanation about $condition and $params.
find()
方法
|
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. |
Finds a single active record with the specified condition.
findAll()
方法
|
public array findAll(mixed $condition='', array $params=array (
))
| ||
| $condition | mixed | query condition or criteria. |
| $params | array | parameters to be bound to an SQL statement. |
| {return} | array | list of active records satisfying the specified condition. An empty array is returned if none is found. |
Finds all active records satisfying the specified condition. See find() for detailed explanation about $condition and $params.
findAllByAttributes()
方法
|
public array findAllByAttributes(array $attributes, mixed $condition='', array $params=array (
))
| ||
| $attributes | array | list of attribute values (indexed by attribute names) that the active records should match. Since version 1.0.8, 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} | array | the records found. An empty array is returned if none is found. |
Finds all active records that have the specified attribute values. See find() for detailed explanation about $condition and $params.
findAllByPk()
方法
|
public array 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} | array | the records found. An empty array is returned if none is found. |
Finds all active records with the specified primary keys. See find() for detailed explanation about $condition and $params.
findAllBySql()
方法
|
public array findAllBySql(string $sql, array $params=array (
))
| ||
| $sql | string | the SQL statement |
| $params | array | parameters to be bound to the SQL statement |
| {return} | array | the records found. An empty array is returned if none is found. |
Finds all active records using the specified SQL statement.
findByAttributes()
方法
|
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. Since version 1.0.8, 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. |
Finds a single active record that has the specified attribute values. See find() for detailed explanation about $condition and $params.
findByPk()
方法
|
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. |
Finds a single active record with the specified primary key. See find() for detailed explanation about $condition and $params.
findBySql()
方法
|
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. |
Finds a single active record with the specified SQL statement.
getActiveRelation()
方法
|
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. |
getAttribute()
方法
|
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. |
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.
参见
getAttributes()
方法
|
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. |
Returns all column attribute values. Note, related objects are not returned.
getCommandBuilder()
方法
|
public CDbCommandBuilder getCommandBuilder()
| ||
| {return} | CDbCommandBuilder | the command builder used by this AR |
getDbConnection()
方法
|
public CDbConnection getDbConnection()
| ||
| {return} | CDbConnection | the database connection used by active record. |
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()
方法
（自版本 v1.0.5 可用）
|
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. |
Returns the query criteria associated with this model.
getIsNewRecord()
方法
|
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. |
getMetaData()
方法
|
public CActiveRecordMetaData getMetaData()
| ||
| {return} | CActiveRecordMetaData | the meta for this AR class. |
getPrimaryKey()
方法
|
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. |
getRelated()
方法
（自版本 v1.0.2 可用）
|
public mixed getRelated(string $name, boolean $refresh=false, array $params=array (
))
| ||
| $name | string | the relation name (see relations) |
| $refresh | boolean | whether to reload the related objects from database. Defaults to false. |
| $params | array | additional parameters that customize the query conditions as specified in the relation declaration. This parameter has been available since version 1.0.5. |
| {return} | mixed | the related object(s). |
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.
getTableSchema()
方法
|
public CDbTableSchema getTableSchema()
| ||
| {return} | CDbTableSchema | the metadata of the table that this AR belongs to |
getValidators()
方法
（自版本 v1.0.1 可用）
|
public array getValidators()
| ||
| {return} | array | a list of validators created according to CModel::rules. |
Returns a list of validators created according to rules. This overrides the parent implementation so that the validators are only created once for each type of AR.
hasAttribute()
方法
|
public boolean hasAttribute(string $name)
| ||
| $name | string | attribute name |
| {return} | boolean | whether this AR has the named attribute (table column). |
hasRelated()
方法
（自版本 v1.0.3 可用）
|
public booolean hasRelated(string $name)
| ||
| $name | string | the relation name |
| {return} | booolean | 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.
init()
方法
（自版本 v1.0.8 可用）
|
public void init()
|
Initializes this model. This method is invoked in the constructor right after scenario is set. You may override this method to provide code that is needed to initialize the model (e.g. setting initial property values.)
insert()
方法
|
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. |
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.
instantiate()
方法
（自版本 v1.0.2 可用）
|
protected CActiveRecord instantiate(array $attributes)
| ||
| $attributes | array | list of attribute values for the active records. |
| {return} | CActiveRecord | the active record |
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()
方法
|
public static CActiveRecord model(string $className='CActiveRecord')
| ||
| $className | string | active record class name. |
| {return} | CActiveRecord | active record model instance. |
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()
方法
（自版本 v1.0.2 可用）
|
public boolean offsetExists(mixed $offset)
| ||
| $offset | mixed | the offset to check on |
| {return} | boolean | |
Returns whether there is an element at the specified offset. This method is required by the interface ArrayAccess.
onAfterConstruct()
方法
（自版本 v1.0.2 可用）
|
public void onAfterConstruct(CEvent $event)
| ||
| $event | CEvent | the event parameter |
This event is raised after the record instance is created by new operator.
onAfterDelete()
方法
（自版本 v1.0.2 可用）
|
public void onAfterDelete(CEvent $event)
| ||
| $event | CEvent | the event parameter |
This event is raised after the record is deleted.
onAfterFind()
方法
（自版本 v1.0.2 可用）
|
public void onAfterFind(CEvent $event)
| ||
| $event | CEvent | the event parameter |
This event is raised after the record is instantiated by a find method.
onAfterSave()
方法
（自版本 v1.0.2 可用）
|
public void onAfterSave(CEvent $event)
| ||
| $event | CEvent | the event parameter |
This event is raised after the record is saved.
onBeforeDelete()
方法
（自版本 v1.0.2 可用）
|
public void onBeforeDelete(CEvent $event)
| ||
| $event | CEvent | the event parameter |
This event is raised before the record is deleted.
onBeforeFind()
方法
（自版本 v1.0.9 可用）
|
public void onBeforeFind(CEvent $event)
| ||
| $event | CEvent | the event parameter |
This event is raised before an AR finder performs a find call.
参见
onBeforeSave()
方法
（自版本 v1.0.2 可用）
|
public void onBeforeSave(CEvent $event)
| ||
| $event | CEvent | the event parameter |
This event is raised before the record is saved.
populateRecord()
方法
|
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. This parameter is added in version 1.0.3. |
| {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. |
Creates an active record with the given attributes. This method is internally used by the find methods.
populateRecords()
方法
|
public array populateRecords(array $data, boolean $callAfterFind=true)
| ||
| $data | array | list of attribute values for the active records. |
| $callAfterFind | boolean | whether to call afterFind after each record is populated. This parameter is added in version 1.0.3. |
| {return} | array | list of active records. |
Creates a list of active records based on the input data. This method is internally used by the find methods.
primaryKey()
方法
（自版本 v1.0.4 可用）
|
public mixed primaryKey()
| ||
| {return} | mixed | the primary key of the associated database table. If the key is a single column, it should return the column name; If the key is a composite one consisting of several columns, it should return the array of the key column names. |
Returns the primary key of the associated database table. This method is meant to be overridden in case when the table is not defined with a primary key (for some legency database). If the table is already defined with a primary key, you do not need to override this method. The default implementation simply returns null, meaning using the primary key defined in the database.
refresh()
方法
|
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. |
Repopulates this active record with the latest data.
refreshMetaData()
方法
（自版本 v1.0.8 可用）
|
public void 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.
relations()
方法
|
public array relations()
| ||
| {return} | array | list of related object declarations. Defaults to empty 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.
By declaring these relations, CActiveRecord can bring back related objects in either lazy loading or eager loading approach, and you save the effort of writing complex JOIN SQL statements.
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 must be listed together, separating with space or comma;
and for foreign keys used in MANY_MANY relation, the joining table must be declared as well
(e.g. 'joinTable(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(??.name) AS name_count).
- 'condition': string, the WHERE clause. Defaults to empty. Note, column references need to be disambiguated with prefix '??.' (e.g. ??.age>20)
- 'order': string, the ORDER BY clause. Defaults to empty. Note, column references need to be disambiguated with prefix '??.' (e.g. ??.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'.
- 'aliasToken': the column prefix for column reference disambiguation. Defaults to '??.'.
- 'alias': the alias for the table associated with this relationship. This option has been available since version 1.0.1. It defaults to null, meaning the table alias is automatically generated. This is different from `aliasToken` in that the latter is just a placeholder and will be replaced by the actual table alias.
- 'params': the parameters to be bound to the generated SQL statement. This should be given as an array of name-value pairs. This option has been available since version 1.0.3.
- 'on': the ON clause. The condition specified here will be appended to the joining condition using the AND operator. This option has been available since version 1.0.2.
- '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. This option has been available since version 1.0.7.
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 '??.' (e.g. ??.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 '??.' (e.g. ??.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.
Below is an example declaring related objects for 'Post' active record class:
return array(
'author'=>array(self::BELONGS_TO, 'User', 'authorID'),
'comments'=>array(self::HAS_MANY, 'Comment', 'postID', 'with'=>'author', 'order'=>'createTime DESC'),
'tags'=>array(self::MANY_MANY, 'Tag', 'PostTag(postID, tagID)', 'order'=>'name'),
);
safeAttributes()
方法
|
public array safeAttributes()
| ||
| {return} | array | list of safe attribute names. |
Returns the name of attributes that are safe to be massively assigned. The default implementation returns all table columns exception primary key(s). Child class may override this method to further limit the attributes that can be massively assigned. See CModel::safeAttributes on how to override this method.
save()
方法
|
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. The validation will be performed under either 'insert' or 'update' scenario, depending on whether isNewRecord is true or false. |
| $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 |
Saves the current record. The record is inserted as a row into the database table if it is manually created using the 'new' operator. If it is obtained using one of those 'find' methods, the record is considered not new and it will be used to update the corresponding row in the table. You may check this status via isNewRecord. Validation may be performed before saving the record. If the validation fails, the record will not be saved. If the record is being inserted and its primary key is null, after insertion the primary key will be populated with the value generated automatically by the database.
saveAttributes()
方法
|
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 |
Saves a selected list of attributes. Unlike save, this method only saves the specified attributes of an existing row dataset. It thus has better performance. Note, 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();
scopes()
方法
（自版本 v1.0.5 可用）
|
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. |
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'=>'createTime 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()
方法
|
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 |
Sets the named attribute value. You may also use $this->AttributeName to set the attribute value.
参见
setIsNewRecord()
方法
|
public void setIsNewRecord(boolean $value)
| ||
| $value | boolean | whether the record is new and should be inserted when calling save. |
tableName()
方法
|
public string tableName()
| ||
| {return} | string | the table name |
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.
update()
方法
|
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 |
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()
方法
|
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 |
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()
方法
|
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 |
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()
方法
|
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 |
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.
with()
方法
|
public CActiveFinder with()
| ||
| {return} | CActiveFinder | the active finder instance. If no parameter is passed in, the object itself will be returned. |
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'=>'createTime'),
))->findAll();
This method returns a CActiveFinder instance that provides a set of find methods similar to that of CActiveRecord.
Note, the possible parameters to this method have been changed since version 1.0.2. Previously, it was not possible to specify on-th-fly query options, and child-relations were specified as hierarchical arrays.