Abstract Class yii\db\BaseActiveRecord

PHP getter magic method.

This method is overridden so that attributes and related objects can be accessed like properties.

参见 getAttribute().

Checks if a property value is null.

This method overrides the parent implementation by checking if the named attribute is null or not.

PHP setter magic method.

This method is overridden so that AR attributes can be accessed like properties.

Sets a component property to be null.

This method overrides the parent implementation by clearing the specified attribute value.

This method is invoked after deleting a record.

The default implementation raises the EVENT_AFTER_DELETE 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 called when the AR object is created and populated with the query result.

The default implementation will trigger an EVENT_AFTER_FIND event. When overriding this method, make sure you call the parent implementation to ensure the event is triggered.

This method is called when the AR object is refreshed.

The default implementation will trigger an EVENT_AFTER_REFRESH event. When overriding this method, make sure you call the parent implementation to ensure the event is triggered.

This method is called at the end of inserting or updating a record.

The default implementation will trigger an EVENT_AFTER_INSERT event when $insert is true, or an EVENT_AFTER_UPDATE event if $insert is false. The event class used is yii\db\AfterSaveEvent. When overriding this method, make sure you call the parent implementation so that the event is triggered.

This method is invoked before deleting a record.

The default implementation raises the EVENT_BEFORE_DELETE event. When overriding this method, make sure you call the parent implementation like the following:

public function beforeDelete()
{
    if (!parent::beforeDelete()) {
        return false;
    }

    // ...custom code here...
    return true;
}

This method is called at the beginning of inserting or updating a record.

The default implementation will trigger an EVENT_BEFORE_INSERT event when $insert is true, or an EVENT_BEFORE_UPDATE event if $insert is false. When overriding this method, make sure you call the parent implementation like the following:

public function beforeSave($insert)
{
    if (!parent::beforeSave($insert)) {
        return false;
    }

    // ...custom code here...
    return true;
}

Returns a value indicating whether a property can be read.

A property can be read if:

• the class has a getter method associated with the specified name (in this case, property name is case-insensitive);
• the class has a member variable with the specified name (when $checkVars is true);
• an attached behavior has a readable property of the given name (when $checkBehaviors is true).

Returns a value indicating whether a property can be set.

A property can be written if:

• the class has a setter method associated with the specified name (in this case, property name is case-insensitive);
• the class has a member variable with the specified name (when $checkVars is true);
• an attached behavior has a writable property of the given name (when $checkBehaviors is true).

Creates a query instance for has-one or has-many relation.

参见：

• hasOne()
• hasMany()

Deletes the table row corresponding to this active record.

This method performs the following steps in order:

1. call beforeDelete(). If the method returns false, it will skip the rest of the steps;
2. delete the record from the database;
3. call afterDelete().

In the above step 1 and 3, events named EVENT_BEFORE_DELETE and EVENT_AFTER_DELETE will be raised by the corresponding methods.

Deletes rows in the table using the provided conditions.

WARNING: If you do not specify any condition, this method will delete ALL rows in the table.

For example, to delete all customers whose status is 3:

Customer::deleteAll('status = 3');

Returns a value indicating whether the given active record is the same as the current one.

The comparison is made by comparing the table names and the primary key values of the two active records. If one of the records is new they are also considered not equal.

Returns the list of fields that can be expanded further and returned by toArray().

The default implementation returns the names of the relations that have been populated into this record.

This method is similar to fields() except that the list of fields returned by this method are not returned by default by toArray(). Only when field names to be expanded are explicitly specified when calling toArray(), will their values be exported.

The default implementation returns an empty array.

You may override this method to return a list of expandable fields based on some context information (e.g. the current application user).

Returns the list of fields that should be returned by default by toArray() when no specific fields are specified.

The default implementation returns the names of the columns whose values have been populated into this record.

A field is a named element in the returned array by toArray().

This method should return an array of field names or field definitions. If the former, the field name will be treated as an object property name whose value will be used as the field value. If the latter, the array key should be the field name while the array value should be the corresponding field definition which can be either an object property name or a PHP callable returning the corresponding field value. The signature of the callable should be:

function ($model, $field) {
    // return field value
}

For example, the following code declares four fields:

• email: the field name is the same as the property name email;
• firstName and lastName: the field names are firstName and lastName, and their values are obtained from the first_name and last_name properties;
• fullName: the field name is fullName. Its value is obtained by concatenating first_name and last_name.

return [
    'email',
    'firstName' => 'first_name',
    'lastName' => 'last_name',
    'fullName' => function ($model) {
        return $model->first_name . ' ' . $model->last_name;
    },
];

In this method, you may also want to return different lists of fields based on some context information. For example, depending on $scenario or the privilege of the current application user, you may return different sets of visible fields or filter out some fields.

The default implementation of this method returns attributes() indexed by the same attribute names.

返回与指定的主键值或一组列值匹配的活动记录模型的列表。

The method accepts:

• 标量值（integer 或 string）：通过单个主键值进行查询并返回包含相应记录的数组 （如果未找到则返回空数组）。
• 非关联数组：按主键值列表查询并返回相应记录 （如果没有找到则返回空数组）。 注意，空条件将导致空结果， 因为它将被解释为搜索结果主键而不是空的 WHERE 条件。
• 一个键值对关联数组：通过一组属性值进行查询， 并返回所有属性值匹配的记录数组（如果没有找到则返回空数组） 请注意，['id' => 1, 2] 被视为非关联数组。 列名仅限于 SQL DBMS 的当前记录表列，否则将过滤以限制为简单的过滤条件。

此方法将自动调用 all() 方法并返回 ActiveRecord 实例的数组。

Note：因为只是一种简单的方法，所以使用更复杂的条件，比如 ['!=', 'id', 1] 将不起作用。 如果需要指定更复杂的条件，请将 find() 与 where() 组合使用。

有关于用法示例，请参阅以下代码：

// 找到主键值为 10 的客户
$customers = Customer::findAll(10);

// 上面的代码相当于：
$customers = Customer::find()->where(['id' => 10])->all();

// 找到主键值为 10，11 或 12 的客户。
$customers = Customer::findAll([10, 11, 12]);

// 上面的代码相当于：
$customers = Customer::find()->where(['id' => [10, 11, 12]])->all();

// 找到年龄为 30 岁且状态为 1 的客户
$customers = Customer::findAll(['age' => 30, 'status' => 1]);

// 上面的代码相当于：
$customers = Customer::find()->where(['age' => 30, 'status' => 1])->all();

如果需要将用户输入传递给此方法，在输入值是标量或在数组条件情况下， 确保无法从外部更改数组数组结构：

// yii\web\Controller ensures that $id is scalar
public function actionView($id)
{
    $model = Post::findOne($id);
    // ...
}

// 显式指定要搜索的列，在此处传递标量或数组将始终导致查找单个记录
$model = Post::findOne(['id' => Yii::$app->request->get('id')]);

// 不要使用以下代码！可以通过任意列值注入数组条件来过滤！
$model = Post::findOne(Yii::$app->request->get('id'));

Finds ActiveRecord instance(s) by the given condition.

This method is internally called by findOne() and findAll().

通过主键或列值数组返回单个活动记录模型实例。

该方法接受：

• 标量值（integer 或 string）：按单个主键值查询并返回记录 （如果未找到就返回 null）。
• 一个非关联数组：按主键值列表查询并返回第一条记录 （如果未找到就返回 null）。
• 一个键值对：通过一组属性值进行查询，并返回匹配所有属性值的单个记录（如果未找到就返回 null）。 注意，['id' => 1, 2] 被视为非关联数组。 列名仅限于 SQL DBMS 的当前记录列表，或者过滤为限制为简单的过滤条件。

该方法将自动调用 one() 方法并且返回 ActiveRecord 实例。

Note: 因为只是一种简单的方法，所以使用更复杂的条件，比如 ['!=', 'id', 1] 将不起作用。 如果需要指定更复杂的条件，请将 find() 与 where() 组合使用。

有关用法的示例，请参阅以下代码：

// 找到主键值为 10 的单个客户
$customer = Customer::findOne(10);

// 上面的代码相当于：
$customer = Customer::find()->where(['id' => 10])->one();

// 找到主键值为 10，11 或 12 的客户。
$customers = Customer::findOne([10, 11, 12]);

// 上面的代码相当于：
$customers = Customer::find()->where(['id' => [10, 11, 12]])->one();

// 找到第一个年龄为 30 岁且状态为 1 的客户
$customer = Customer::findOne(['age' => 30, 'status' => 1]);

// 上面的代码相当于：
$customer = Customer::find()->where(['age' => 30, 'status' => 1])->one();

如果需要将用户输入传递给此方法，在输入值是标量或在数组条件情况下， 确保无法从外部更改数组结构：

// yii\web\Controller ensures that $id is scalar
public function actionView($id)
{
    $model = Post::findOne($id);
    // ...
}

// 显示指定要搜索的列，在此处传递标量或数组将始终导致查询单个记录
$model = Post::findOne(['id' => Yii::$app->request->get('id')]);

// 不要使用以下代码！可以通过任意列值注入数组条件来过滤！
$model = Post::findOne(Yii::$app->request->get('id'));

Returns the named attribute value.

If this record is the result of a query and the attribute is not loaded, null will be returned.

参见 hasAttribute().

Returns the text hint for the specified attribute.

If the attribute looks like relatedModel.attribute, then the attribute will be received from the related model.

参见 attributeHints().

Returns the text label for the specified attribute.

If the attribute looks like relatedModel.attribute, then the attribute will be received from the related model.

参见：

• generateAttributeLabel()
• attributeLabels()

Returns the attribute values that have been modified since they are loaded or saved most recently.

The comparison of new and old values is made for identical values using ===.

Returns a value indicating whether the current record is new.

Returns the old value of the named attribute.

If this record is the result of a query and the attribute is not loaded, null will be returned.

参见 hasAttribute().

Returns the old attribute values.

Returns the old primary key value(s).

This refers to the primary key value that is populated into the record after executing a find method (e.g. find(), findOne()). The value remains unchanged even if the primary key attribute is manually assigned with a different value.

Returns the primary key value(s).

Returns all populated related records.

参见 getRelation().

Returns the relation object with the specified name.

A relation is defined by a getter method which returns an yii\db\ActiveQueryInterface object. It can be declared in either the Active Record class itself or one of its behaviors.

Returns a value indicating whether the model has an attribute with the specified name.

Declares a has-many relation.

The declaration is returned in terms of a relational yii\db\ActiveQuery instance through which the related record can be queried and retrieved back.

A has-many relation means that there are multiple related records matching the criteria set by this relation, e.g., a customer has many orders.

For example, to declare the orders relation for Customer class, we can write the following code in the Customer class:

public function getOrders()
{
    return $this->hasMany(Order::className(), ['customer_id' => 'id']);
}

Note that in the above, the 'customer_id' key in the $link parameter refers to an attribute name in the related class Order, while the 'id' value refers to an attribute name in the current AR class.

Call methods declared in yii\db\ActiveQuery to further customize the relation.

Declares a has-one relation.

The declaration is returned in terms of a relational yii\db\ActiveQuery instance through which the related record can be queried and retrieved back.

A has-one relation means that there is at most one related record matching the criteria set by this relation, e.g., a customer has one country.

For example, to declare the country relation for Customer class, we can write the following code in the Customer class:

public function getCountry()
{
    return $this->hasOne(Country::className(), ['id' => 'country_id']);
}

Note that in the above, the 'id' key in the $link parameter refers to an attribute name in the related class Country, while the 'country_id' value refers to an attribute name in the current AR class.

Call methods declared in yii\db\ActiveQuery to further customize the relation.

Initializes the object.

This method is called at the end of the constructor. The default implementation will trigger an EVENT_INIT event.

Creates an active record instance.

This method is called together with populateRecord() by yii\db\ActiveQuery. It is not meant to be used for creating new records directly.

You may override this method if the instance being created depends on the row data to be populated into 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.

Returns a value indicating whether the named attribute has been changed.

Returns a value indicating whether the given set of attributes represents the primary key for this model.

Check whether the named relation has been populated with records.

参见 getRelation().

Establishes the relationship between two models.

The relationship is established by setting the foreign key value(s) in one model to be the corresponding primary key value(s) in the other model. The model with the foreign key will be saved into database without performing validation.

If the relationship involves a junction table, a new row will be inserted into the junction table which contains the primary key values from both models.

Note that this method requires that the primary key value is not null.

Marks an attribute dirty.

This method may be called to force updating a record when calling update(), even if there is no change being made to the record.

Returns whether there is an element at the specified offset.

This method is required by the interface ArrayAccess.

Sets the element value at the specified offset to null.

This method is required by the SPL interface ArrayAccess. It is implicitly called when you use something like unset($model[$offset]).

Returns the name of the column that stores the lock version for implementing optimistic locking.

Optimistic locking allows multiple users to access the same record for edits and avoids potential conflicts. In case when a user attempts to save the record upon some staled data (because another user has modified the data), a yii\db\StaleObjectException exception will be thrown, and the update or deletion is skipped.

Optimistic locking is only supported by update() and delete().

To use Optimistic locking:

1. Create a column to store the version number of each row. The column type should be BIGINT DEFAULT 0. Override this method to return the name of this column.
2. Ensure the version value is submitted and loaded to your model before any update or delete. Or add OptimisticLockBehavior to your model class in order to automate the process.
3. In the Web form that collects the user input, add a hidden field that stores the lock version of the recording being updated.
4. In the controller action that does the data updating, try to catch the yii\db\StaleObjectException and implement necessary business logic (e.g. merging the changes, prompting stated data) to resolve the conflict.

Populates an active record object using a row of data from the database/storage.

This is an internal method meant to be called to create active record objects after fetching data from the database. It is mainly used by yii\db\ActiveQuery to populate the query results into active records.

When calling this method manually you should call afterFind() on the created record to trigger the afterFind Event.

Populates the named relation with the related records.

Note that this method does not check if the relation exists or not.

参见 getRelation().

Repopulates this active record with the latest data.

If the refresh is successful, an EVENT_AFTER_REFRESH event will be triggered. This event is available since version 2.0.8.

Repopulates this active record with the latest data from a newly fetched instance.

参见 refresh().

Saves the current record.

This method will call insert() when $isNewRecord is true, or update() when $isNewRecord is false.

For example, to save a customer record:

$customer = new Customer; // or $customer = Customer::findOne($id);
$customer->name = $name;
$customer->email = $email;
$customer->save();

Sets the named attribute value.

参见 hasAttribute().

Sets the value indicating whether the record is new.

参见 getIsNewRecord().

Sets the old value of the named attribute.

参见 hasAttribute().

Sets the old attribute values.

All existing old attribute values will be discarded.

Destroys the relationship between two models.

The model with the foreign key of the relationship will be deleted if $delete is true. Otherwise, the foreign key will be set null and the model will be saved without validation.

Destroys the relationship in current model.

The model with the foreign key of the relationship will be deleted if $delete is true. Otherwise, the foreign key will be set null and the model will be saved without validation.

Note that to destroy the relationship without removing records make sure your keys can be set to null

Saves the changes to this active record into the associated database table.

This method performs the following steps in order:

1. call beforeValidate() when $runValidation is true. If beforeValidate() returns false, the rest of the steps will be skipped;
2. call afterValidate() when $runValidation is true. If validation failed, the rest of the steps will be skipped;
3. call beforeSave(). If beforeSave() returns false, the rest of the steps will be skipped;
4. save the record into database. If this fails, it will skip the rest of the steps;
5. call afterSave();

In the above step 1, 2, 3 and 5, events EVENT_BEFORE_VALIDATE, EVENT_AFTER_VALIDATE, EVENT_BEFORE_UPDATE, and EVENT_AFTER_UPDATE will be raised by the corresponding methods.

Only the changed attribute values will be saved into database.

For example, to update a customer record:

$customer = Customer::findOne($id);
$customer->name = $name;
$customer->email = $email;
$customer->update();

Note that it is possible the update does not affect any row in the table. In this case, this method will return 0. For this reason, you should use the following code to check if update() is successful or not:

if ($customer->update() !== false) {
    // update successful
} else {
    // update failed
}

Updates the whole table using the provided attribute values and conditions.

For example, to change the status to be 1 for all customers whose status is 2:

Customer::updateAll(['status' => 1], 'status = 2');

Updates the whole table using the provided counter changes and conditions.

For example, to increment all customers' age by 1,

Customer::updateAllCounters(['age' => 1]);

Updates the specified attributes.

This method is a shortcut to update() when data validation is not needed and only a small set attributes need to be updated.

You may specify the attributes to be updated as name list or name-value pairs. If the latter, the corresponding attribute values will be modified accordingly. The method will then save the specified attributes into database.

Note that this method will not perform data validation and will not trigger events.

Updates one or several counter columns for the current AR object.

Note that this method differs from updateAllCounters() in that it only saves counters for the current AR object.

An example usage is as follows:

$post = Post::findOne($id);
$post->updateCounters(['view_count' => 1]);

参见 updateAllCounters().

参见 update().