没有命名空间的类 yii yii\base yii\behaviors yii\caching yii\captcha yii\console yii\console\controllers yii\console\widgets yii\data yii\db yii\db\conditions yii\db\cubrid yii\db\cubrid\conditions yii\db\mssql yii\db\mssql\conditions yii\db\mysql yii\db\oci yii\db\oci\conditions yii\db\pgsql yii\db\sqlite yii\db\sqlite\conditions yii\di yii\filters yii\filters\auth yii\grid yii\helpers yii\i18n yii\log yii\mail yii\mutex yii\rbac yii\rest yii\test yii\validators yii\web yii\widgets

Class yii\db\ActiveRecord

继承yii\db\ActiveRecord » yii\db\BaseActiveRecord » yii\base\Model » yii\base\Component » yii\base\BaseObject
实现ArrayAccess, IteratorAggregate, yii\base\Arrayable, yii\base\Configurable, yii\base\StaticInstanceInterface, yii\db\ActiveRecordInterface
使用 Traitsyii\base\ArrayableTrait, yii\base\StaticInstanceTrait
可用版本自2.0
源码 https://github.com/yiichina/yii2/blob/api/framework/db/ActiveRecord.php

ActiveRecord 是表示数据对象关系的类的基类。

ActiveRecord 实现请阅读 Active Record design pattern。 Active Record 背后的前提是,单个 yii\db\ActiveRecord 对象与数据库表中的特定行相关联。 对象的属性映射到相应表的列。 引用 Active Record 属性等同于访问该记录的相应表列。

例如,假设 Customer ActiveRecord 类与 customer 表相关联。 这意味着类的 name 属性会自动映射到 customer 表中的 name 列。 感谢伟大的 Active Record,当变量 $customerCustomer 类的对象时, 为了得到表行的 name 列的值,你可以使用表达式 $customer->name 获取它。 在此示例中,ActiveRecord 提供了一个面向对象的接口,用于访问存储在数据库中的数据。 但 Active Record 提供了比这更多的功能。

要声明一个 ActiveRecord 类, 你需要继承 yii\db\ActiveRecord 并实现 tableName 方法:

<?php

class Customer extends \yii\db\ActiveRecord
{
    public static function tableName()
    {
        return 'customer';
    }
}

tableName 方法仅会返回与该类关联的数据库表的名称。

提示:您还可以使用 Gii code generator 从数据库表生成 ActiveRecord 类。

类实例可通过以下两种方式的任何一种获得:

  • 使用 new 操作符,创建一个新的空对象
  • 使用方法从数据库中获取现有记录(或记录)

下面是一个示例,显示 ActiveRecord 的一些典型用法:

$user = new User();
$user->name = 'Qiang';
$user->save();  // a new row is inserted into user table

// the following will retrieve the user 'CeBe' from the database
$user = User::find()->where(['name' => 'CeBe'])->one();

// this will get related records from orders table when relation is defined
$orders = $user->orders;

有关 ActiveRecord 的更多详细信息和用法,请参阅 guide article on ActiveRecord

公共属性

隐藏继承的属性

属性类型描述被定义在
$activeValidators yii\validators\Validator[] The validators applicable to the current $scenario. yii\base\Model
$attributes array Attribute values (name => value). yii\base\Model
$behaviors yii\base\Behavior[] List of behaviors attached to this component yii\base\Component
$dirtyAttributes array The changed attribute values (name-value pairs) yii\db\BaseActiveRecord
$errors array Errors for all attributes or the specified attribute. yii\base\Model
$firstErrors array The first errors. yii\base\Model
$isNewRecord boolean Whether the record is new and should be inserted when calling save(). yii\db\BaseActiveRecord
$iterator ArrayIterator An iterator for traversing the items in the list. yii\base\Model
$oldAttributes array The old attribute values (name-value pairs) yii\db\BaseActiveRecord
$oldPrimaryKey mixed The old primary key value. yii\db\BaseActiveRecord
$primaryKey mixed The primary key value. yii\db\BaseActiveRecord
$relatedRecords array An array of related records indexed by relation names. yii\db\BaseActiveRecord
$scenario string The scenario that this model is in. yii\base\Model
$validators ArrayObject|yii\validators\Validator[] All the validators declared in the model. yii\base\Model

公共方法

隐藏继承的方法

方法描述被定义在
__call() Calls the named method which is not a class method. yii\base\Component
__clone() This method is called after the object is created by cloning an existing one. yii\base\Component
__construct() Constructor. yii\base\BaseObject
__get() PHP getter magic method. yii\db\BaseActiveRecord
__isset() Checks if a property value is null. yii\db\BaseActiveRecord
__set() PHP setter magic method. yii\db\BaseActiveRecord
__unset() Sets a component property to be null. yii\db\BaseActiveRecord
activeAttributes() Returns the attribute names that are subject to validation in the current scenario. yii\base\Model
addError() Adds a new error to the specified attribute. yii\base\Model
addErrors() Adds a list of errors. yii\base\Model
afterDelete() This method is invoked after deleting a record. yii\db\BaseActiveRecord
afterFind() This method is called when the AR object is created and populated with the query result. yii\db\BaseActiveRecord
afterRefresh() This method is called when the AR object is refreshed. yii\db\BaseActiveRecord
afterSave() This method is called at the end of inserting or updating a record. yii\db\BaseActiveRecord
afterValidate() This method is invoked after validation ends. yii\base\Model
attachBehavior() Attaches a behavior to this component. yii\base\Component
attachBehaviors() Attaches a list of behaviors to the component. yii\base\Component
attributeHints() Returns the attribute hints. yii\base\Model
attributeLabels() Returns the attribute labels. yii\base\Model
attributes() 返回模型的所有的属性名称的列表。 默认实现将返回与此 AR 类关联的表的所有列名。 yii\db\ActiveRecord
beforeDelete() This method is invoked before deleting a record. yii\db\BaseActiveRecord
beforeSave() This method is called at the beginning of inserting or updating a record. yii\db\BaseActiveRecord
beforeValidate() This method is invoked before validation starts. yii\base\Model
behaviors() Returns a list of behaviors that this component should behave as. yii\base\Component
canGetProperty() Returns a value indicating whether a property can be read. yii\db\BaseActiveRecord
canSetProperty() Returns a value indicating whether a property can be set. yii\db\BaseActiveRecord
className() Returns the fully qualified name of this class. yii\base\BaseObject
clearErrors() Removes errors for all attributes or a single attribute. yii\base\Model
createValidators() Creates validator objects based on the validation rules specified in rules(). yii\base\Model
delete() 删除与此活动记录对应的表行。 yii\db\ActiveRecord
deleteAll() 使用提供的条件删除表中的行。 yii\db\ActiveRecord
detachBehavior() Detaches a behavior from the component. yii\base\Component
detachBehaviors() Detaches all behaviors from the component. yii\base\Component
ensureBehaviors() Makes sure that the behaviors declared in behaviors() are attached to this component. yii\base\Component
equals() 返回一个给定值,指示给定的活动记录是否与当前记录相同。 通过比较两个活动记录的表名和主键值来进行比较。 如果其中一个记录 is new 也会被认为不相同。 yii\db\ActiveRecord
extraFields() Returns the list of fields that can be expanded further and returned by toArray(). yii\base\ArrayableTrait
fields() Returns the list of fields that should be returned by default by toArray() when no specific fields are specified. yii\base\ArrayableTrait
find() 创建用来查询的 yii\db\ActiveQueryInterface 实例。 yii\db\ActiveRecord
findAll() 返回与指定的主键值或一组列值匹配的活动记录模型的列表。 yii\db\BaseActiveRecord
findBySql() 使用给定的 SQL 语句创建 yii\db\ActiveQuery 实例。 yii\db\ActiveRecord
findOne() 通过主键或列值数组返回单个活动记录模型实例。 yii\db\BaseActiveRecord
formName() Returns the form name that this model class should use. yii\base\Model
generateAttributeLabel() Generates a user friendly attribute label based on the give attribute name. yii\base\Model
getActiveValidators() Returns the validators applicable to the current $scenario. yii\base\Model
getAttribute() Returns the named attribute value. yii\db\BaseActiveRecord
getAttributeHint() Returns the text hint for the specified attribute. yii\db\BaseActiveRecord
getAttributeLabel() Returns the text label for the specified attribute. yii\db\BaseActiveRecord
getAttributes() Returns attribute values. yii\base\Model
getBehavior() Returns the named behavior object. yii\base\Component
getBehaviors() Returns all behaviors attached to this component. yii\base\Component
getDb() 返回此 AR 类使用的数据库连接。 默认情况下,"db" 组件用作数据库连接。 如果要使用其他数据库连接,可以重写此方法。 yii\db\ActiveRecord
getDirtyAttributes() Returns the attribute values that have been modified since they are loaded or saved most recently. yii\db\BaseActiveRecord
getErrorSummary() Returns the errors for all attributes as a one-dimensional array. yii\base\Model
getErrors() Returns the errors for all attributes or a single attribute. yii\base\Model
getFirstError() Returns the first error of the specified attribute. yii\base\Model
getFirstErrors() Returns the first error of every attribute in the model. yii\base\Model
getIsNewRecord() Returns a value indicating whether the current record is new. yii\db\BaseActiveRecord
getIterator() Returns an iterator for traversing the attributes in the model. yii\base\Model
getOldAttribute() Returns the old value of the named attribute. yii\db\BaseActiveRecord
getOldAttributes() Returns the old attribute values. yii\db\BaseActiveRecord
getOldPrimaryKey() Returns the old primary key value(s). yii\db\BaseActiveRecord
getPrimaryKey() Returns the primary key value(s). yii\db\BaseActiveRecord
getRelatedRecords() Returns all populated related records. yii\db\BaseActiveRecord
getRelation() Returns the relation object with the specified name. yii\db\BaseActiveRecord
getScenario() Returns the scenario that this model is used in. yii\base\Model
getTableSchema() 返回与此 AR 类关联的 DB 表的结构信息。 yii\db\ActiveRecord
getValidators() Returns all the validators declared in rules(). yii\base\Model
hasAttribute() Returns a value indicating whether the model has an attribute with the specified name. yii\db\BaseActiveRecord
hasErrors() Returns a value indicating whether there is any validation error. yii\base\Model
hasEventHandlers() Returns a value indicating whether there is any handler attached to the named event. yii\base\Component
hasMany() Declares a has-many relation. yii\db\BaseActiveRecord
hasMethod() Returns a value indicating whether a method is defined. yii\base\Component
hasOne() Declares a has-one relation. yii\db\BaseActiveRecord
hasProperty() Returns a value indicating whether a property is defined for this component. yii\base\Component
init() Initializes the object. yii\db\BaseActiveRecord
insert() 使用此属性的记录值将行插入关联的数据库表中。 yii\db\ActiveRecord
instance() 返回静态类实例,该实例可用于获取 meta 信息 yii\base\StaticInstanceTrait
instantiate() Creates an active record instance. yii\db\BaseActiveRecord
isAttributeActive() Returns a value indicating whether the attribute is active in the current scenario. yii\base\Model
isAttributeChanged() Returns a value indicating whether the named attribute has been changed. yii\db\BaseActiveRecord
isAttributeRequired() Returns a value indicating whether the attribute is required. yii\base\Model
isAttributeSafe() Returns a value indicating whether the attribute is safe for massive assignments. yii\base\Model
isPrimaryKey() Returns a value indicating whether the given set of attributes represents the primary key for this model. yii\db\BaseActiveRecord
isRelationPopulated() Check whether the named relation has been populated with records. yii\db\BaseActiveRecord
isTransactional() 返回一个值,该值表示指定的操作在当前 $scenario 中是否为事务性操作。 yii\db\ActiveRecord
link() Establishes the relationship between two models. yii\db\BaseActiveRecord
load() Populates the model with input data. yii\base\Model
loadDefaultValues() 从数据库表结构加载默认值。 yii\db\ActiveRecord
loadMultiple() Populates a set of models with the data from end user. yii\base\Model
markAttributeDirty() Marks an attribute dirty. yii\db\BaseActiveRecord
off() Detaches an existing event handler from this component. yii\base\Component
offsetExists() Returns whether there is an element at the specified offset. yii\db\BaseActiveRecord
offsetGet() Returns the element at the specified offset. yii\base\Model
offsetSet() Sets the element at the specified offset. yii\base\Model
offsetUnset() Sets the element value at the specified offset to null. yii\db\BaseActiveRecord
on() Attaches an event handler to an event. yii\base\Component
onUnsafeAttribute() This method is invoked when an unsafe attribute is being massively assigned. yii\base\Model
optimisticLock() Returns the name of the column that stores the lock version for implementing optimistic locking. yii\db\BaseActiveRecord
populateRecord() Populates an active record object using a row of data from the database/storage. yii\db\ActiveRecord
populateRelation() Populates the named relation with the related records. yii\db\BaseActiveRecord
primaryKey() 返回此 AR 类的主键名称。 默认实现将返回与此 AR 类 关联的 DB 表中声明的主键。 yii\db\ActiveRecord
refresh() Repopulates this active record with the latest data. yii\db\ActiveRecord
rules() Returns the validation rules for attributes. yii\base\Model
safeAttributes() Returns the attribute names that are safe to be massively assigned in the current scenario. yii\base\Model
save() Saves the current record. yii\db\BaseActiveRecord
scenarios() Returns a list of scenarios and the corresponding active attributes. yii\base\Model
setAttribute() Sets the named attribute value. yii\db\BaseActiveRecord
setAttributes() Sets the attribute values in a massive way. yii\base\Model
setIsNewRecord() Sets the value indicating whether the record is new. yii\db\BaseActiveRecord
setOldAttribute() Sets the old value of the named attribute. yii\db\BaseActiveRecord
setOldAttributes() Sets the old attribute values. yii\db\BaseActiveRecord
setScenario() Sets the scenario for the model. yii\base\Model
tableName() 声明与此 AR 类关联的数据库表的名称。 默认情况下,此方法通过使用前缀 yii\db\Connection::$tablePrefix 调用 yii\helpers\Inflector::camel2id() 来返回类名作为表名。 例如,如果 yii\db\Connection::$tablePrefixtbl_, 则 Customer 变为 tbl_customerOrderItem 变为 tbl_order_item 如果未按约定命名表,则可以重写此方法。 yii\db\ActiveRecord
toArray() Converts the model into an array. yii\base\ArrayableTrait
transactions() 声明应在不同场景的事务中执行那些 DB 操作。 支持的 DB 操作为 OP_INSERTOP_UPDATE 以及 OP_DELETE, 分别对应 insert()update() 以及 delete() 方法, 默认情况下,这些方法不包含在数据库事务中。 yii\db\ActiveRecord
trigger() Triggers an event. yii\base\Component
unlink() Destroys the relationship between two models. yii\db\BaseActiveRecord
unlinkAll() Destroys the relationship in current model. yii\db\BaseActiveRecord
update() 将对此活动记录的更改保存到关联的数据库表中。 yii\db\ActiveRecord
updateAll() 使用提供的属性值和条件更新整个表。 yii\db\ActiveRecord
updateAllCounters() 使用提供的计数器更改条件更新整个表。 yii\db\ActiveRecord
updateAttributes() Updates the specified attributes. yii\db\BaseActiveRecord
updateCounters() Updates one or several counter columns for the current AR object. yii\db\BaseActiveRecord
validate() Performs the data validation. yii\base\Model
validateMultiple() Validates multiple models. yii\base\Model

受保护的方法

隐藏继承的方法

方法描述被定义在
createRelationQuery() Creates a query instance for has-one or has-many relation. yii\db\BaseActiveRecord
deleteInternal() 删除 ActiveRecord 而不考虑事务。 yii\db\ActiveRecord
extractFieldsFor() Extract nested fields from a fields collection for a given root field Nested fields are separated with dots (.). e.g: "item.id" The previous example would extract "id". yii\base\ArrayableTrait
extractRootFields() Extracts the root field names from nested fields. yii\base\ArrayableTrait
filterCondition() 在将数组条件分配给查询过滤器之前对其进行过滤。 yii\db\ActiveRecord
findByCondition() 按给定的条件查找 ActiveRecord 实例。 此方法由 findOne()findAll() 在内部调用。 yii\db\ActiveRecord
insertInternal() 在不考虑事务的情况下将 ActiveRecord 插入到 DB 中。 yii\db\ActiveRecord
refreshInternal() Repopulates this active record with the latest data from a newly fetched instance. yii\db\BaseActiveRecord
resolveFields() Determines which fields can be returned by toArray(). yii\base\ArrayableTrait
updateInternal() yii\db\BaseActiveRecord

Events

隐藏继承的事件

事件类型描述被定义在
EVENT_AFTER_DELETE \yii\db\Event An event that is triggered after a record is deleted. yii\db\BaseActiveRecord
EVENT_AFTER_FIND \yii\db\Event An event that is triggered after the record is created and populated with query result. yii\db\BaseActiveRecord
EVENT_AFTER_INSERT yii\db\AfterSaveEvent An event that is triggered after a record is inserted. yii\db\BaseActiveRecord
EVENT_AFTER_REFRESH \yii\db\Event An event that is triggered after a record is refreshed. (自版本 2.0.8 可用) yii\db\BaseActiveRecord
EVENT_AFTER_UPDATE yii\db\AfterSaveEvent An event that is triggered after a record is updated. yii\db\BaseActiveRecord
EVENT_AFTER_VALIDATE yii\base\Event An event raised at the end of validate() yii\base\Model
EVENT_BEFORE_DELETE yii\base\ModelEvent An event that is triggered before deleting a record. yii\db\BaseActiveRecord
EVENT_BEFORE_INSERT yii\base\ModelEvent An event that is triggered before inserting a record. yii\db\BaseActiveRecord
EVENT_BEFORE_UPDATE yii\base\ModelEvent An event that is triggered before updating a record. yii\db\BaseActiveRecord
EVENT_BEFORE_VALIDATE yii\base\ModelEvent An event raised at the beginning of validate(). yii\base\Model
EVENT_INIT \yii\db\Event An event that is triggered when the record is initialized via init(). yii\db\BaseActiveRecord

常量

隐藏继承的常量

常量描述被定义在
OP_ALL 7 所有三个操作:insert、update、delete。 这是表达式的快捷方式:OP_INSERT | OP_UPDATE | OP_DELETE。 yii\db\ActiveRecord
OP_DELETE 4 删除操作。其主要用于覆盖 transactions() 以指定哪些操作是事务性的。 yii\db\ActiveRecord
OP_INSERT 1 插入操作。其主要用于覆盖 transactions() 以指定哪些操作是事务性的。 yii\db\ActiveRecord
OP_UPDATE 2 更新操作。其主要用于覆盖 transactions() 以指定哪些操作是事务性的。 yii\db\ActiveRecord
SCENARIO_DEFAULT 'default' The name of the default scenario. yii\base\Model

方法详情

attributes() 公共 方法

返回模型的所有的属性名称的列表。 默认实现将返回与此 AR 类关联的表的所有列名。

public array attributes()
return array

属性名称列表。

delete() 公共 方法

删除与此活动记录对应的表行。

此方法将按顺序执行以下步骤:

  1. 调用 beforeDelete()。 如果该方法返回 false,则跳过其余步骤;
  2. 从数据库删除记录;
  3. 调用 afterDelete()

在以上步骤 1 和 3 中, 将通过相应的方法引发事件 EVENT_BEFORE_DELETEEVENT_AFTER_DELETE

public integer|false delete()
return integer|false

删除的行数,如果由于某种原因删除失败,则为 false。 注意,即使删除执行成功,删除的行数也可能为 0。

throws yii\db\StaleObjectException

如果启用了 optimistic locking 并且当正在删除的数据已过时,则抛出异常。

throws \Exception|\Throwable

万一删除失败,则抛出异常。

deleteAll() 公共 静态 方法

使用提供的条件删除表中的行。

例如,要删除所有状态为 3 的客户:

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

警告:如果未指定任何条件,则此方法将删除表中的所有行。

注意,此方法不会触发任何事件。如果需要触发 EVENT_BEFORE_DELETEEVENT_AFTER_DELETE, 则首先需要 find 模型,然后再每个模型上调用 delete()。 例如,下面的例子和前面的例子作用是相同的:

$models = Customer::find()->where('status = 3')->all();
foreach ($models as $model) {
    $model->delete();
}

对于大量模型,可以考虑使用 yii\db\ActiveQuery::each() 将内存使用限制在规定范围内。

public static integer deleteAll($condition null, $params = [])
$condition string|array

将放在 DELETE SQL 的 WHERE 部分中的条件。 有关如何指定此参数,请阅读 yii\db\Query::where()

$params array

要绑定到查询的参数 (name => value)。

return integer

删除的行数

deleteInternal() 受保护 方法

删除 ActiveRecord 而不考虑事务。

protected integer|false deleteInternal()
return integer|false

删除的行数,如果由于某种原因删除失败,则为 false。 注意,即使删除执行成功,删除的行数也可能为 0。

throws yii\db\StaleObjectException
equals() 公共 方法

返回一个给定值,指示给定的活动记录是否与当前记录相同。 通过比较两个活动记录的表名和主键值来进行比较。 如果其中一个记录 is new 也会被认为不相同。

public boolean equals($record)
$record yii\db\ActiveRecord

要比较记录

return boolean

两个活动记录是否引用同一数据库表中的同一行。

filterCondition() 受保护 静态 方法 (自版本 2.0.15 可用)

在将数组条件分配给查询过滤器之前对其进行过滤。

此方法将确保数组条件仅过滤现有表列。

protected static array filterCondition(array $condition)
$condition array

过滤条件。

return array

过滤后的条件。

throws yii\base\InvalidArgumentException

当数组中包含不安全的值时,抛出异常。

find() 公共 静态 方法

创建用来查询的 yii\db\ActiveQueryInterface 实例。

返回的 yii\db\ActiveQueryInterface 实例可以通过调用 one()all() 之前调用 yii\db\ActiveQueryInterface 方法来进一步自定义, 以返回填充的 ActiveRecord 实例。例如,

// 找到 ID 为 1 的客户
$customer = Customer::find()->where(['id' => 1])->one();

// 查找所有活跃客户并按其年龄排序
$customers = Customer::find()
    ->where(['status' => 1])
    ->orderBy('age')
    ->all();

yii\db\BaseActiveRecord::hasOne()yii\db\BaseActiveRecord::hasMany() 也调用此方法来创建关系查询。

你可以覆盖此方法以返回自定义查询。例如,

class Customer extends ActiveRecord
{
    public static function find()
    {
        // use CustomerQuery instead of the default ActiveQuery
        return new CustomerQuery(get_called_class());
    }
}

以下代码显示如何为所有查询应用默认条件:

class Customer extends ActiveRecord
{
    public static function find()
    {
        return parent::find()->where(['deleted' => false]);
    }
}

// 使用 andWhere()/orWhere() 应用默认条件
// SELECT FROM customer WHERE `deleted`=:deleted AND age>30
$customers = Customer::find()->andWhere('age>30')->all();

// 使用 where() 忽略默认条件
// SELECT FROM customer WHERE age>30
$customers = Customer::find()->where('age>30')->all();


public static yii\db\ActiveQuery find()
return yii\db\ActiveQuery

新建的 yii\db\ActiveQuery 实例。

findByCondition() 受保护 静态 方法

按给定的条件查找 ActiveRecord 实例。 此方法由 findOne()findAll() 在内部调用。

protected static yii\db\ActiveQueryInterface findByCondition($condition)
$condition mixed

有关此参数的说明请参阅 findOne()

return yii\db\ActiveQueryInterface

新创建的 ActiveQuery 实例。

throws yii\base\InvalidConfigException

如果没有定义主键,则抛出异常。

findBySql() 公共 静态 方法

使用给定的 SQL 语句创建 yii\db\ActiveQuery 实例。

请注意,因为已经指定了 SQL 语句, 所以在创建的 yii\db\ActiveQuery 实例上调用其他查询修改方法(例如 where()order()), 将不起作用, 但是,调用 with()asArray()indexBy() 仍然没问题。

下面举个例子:

$customers = Customer::findBySql('SELECT * FROM customer')->all();
public static yii\db\ActiveQuery findBySql($sql, $params = [])
$sql string

要执行的 SQL 语句

$params array

在执行期间绑定到 SQL 语句的参数。

return yii\db\ActiveQuery

新创建的 yii\db\ActiveQuery 实例

getDb() 公共 静态 方法

返回此 AR 类使用的数据库连接。 默认情况下,"db" 组件用作数据库连接。 如果要使用其他数据库连接,可以重写此方法。

public static yii\db\Connection getDb()
return yii\db\Connection

此 AR 类使用的数据库连接。

getTableSchema() 公共 静态 方法

返回与此 AR 类关联的 DB 表的结构信息。

public static yii\db\TableSchema getTableSchema()
return yii\db\TableSchema

与此 AR 类关联的 DB 表的结构信息。

throws yii\base\InvalidConfigException

如果 AR 类的表不存在,抛出异常。

insert() 公共 方法

使用此属性的记录值将行插入关联的数据库表中。

此方法按顺序执行以下步骤:

  1. $runValidationtrue 时调用 beforeValidate()。 如果 beforeValidate() 返回 false,则跳过其余步骤;
  2. $runValidationtrue 时调用 afterValidate()。 如果验证失败,则跳过其余步骤;
  3. 调用 beforeSave()。当 beforeSave() 返回 false, 则跳过其余步骤;
  4. 插入记录到数据库。如果插入记录失败,则跳过其余步骤;
  5. 调用 afterSave()

在上面的步骤 1,2,3 和 5 中, 将通过相应的方法引发事件 EVENT_BEFORE_VALIDATEEVENT_AFTER_VALIDATEEVENT_BEFORE_INSERT,以及 EVENT_AFTER_INSERT

只有 changed attribute values 才会插入到数据库中。

如果表的主键是自动增量并且在插入期间为 null, 则插入后将填充实际值。

例如,要插入 customer 记录:

$customer = new Customer;
$customer->name = $name;
$customer->email = $email;
$customer->insert();
public boolean insert($runValidation true, $attributes null)
$runValidation boolean

是否在保存记录之前执行验证(调用 validate())。 默认为 true,即执行验证。如果验证失败,则记录不会保存到数据库中, 并且此方法将返回 false

$attributes array

需要保存的属性列表。 默认为 null,表示将保存从 DB 加载的所有属性。

return boolean

属性是否有效,以及是否成功插入记录。

throws \Exception|\Throwable

如果插入失败,则抛出异常。

insertInternal() 受保护 方法

在不考虑事务的情况下将 ActiveRecord 插入到 DB 中。

protected boolean insertInternal($attributes null)
$attributes array

需要保存的属性列表。 默认为 null,表示将保存从 DB 加载的所有属性。

return boolean

是否成功插入记录。

isTransactional() 公共 方法

返回一个值,该值表示指定的操作在当前 $scenario 中是否为事务性操作。

public boolean isTransactional($operation)
$operation integer

要检查的操作。可能的值为 OP_INSERTOP_UPDATE 以及 OP_DELETE

return boolean

指定的操作在当前 $scenario 中是否是事务性的。

loadDefaultValues() 公共 方法

从数据库表结构加载默认值。

你可以在创建新实例后调用此方法以加载默认值:

// class Customer extends \yii\db\ActiveRecord
$customer = new Customer();
$customer->loadDefaultValues();
public $this loadDefaultValues($skipIfSet true)
$skipIfSet boolean

是否应保留现有值。 这只会为 null 属性设置默认值。

return $this

模型实例本身。

populateRecord() 公共 静态 方法

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.

public static void populateRecord($record, $row)
$record yii\db\BaseActiveRecord

The record to be populated. In most cases this will be an instance created by instantiate() beforehand.

$row array

Attribute values (name => value)

primaryKey() 公共 静态 方法

返回此 AR 类的主键名称。 默认实现将返回与此 AR 类 关联的 DB 表中声明的主键。

如果 DB 表中为声明任何主键, 则应重写此方法, 以返回要用作此 AR 类的主键属性。

请注意,即使对于具有单个主键的表,也应返回一个数组。

public static string[] primaryKey()
return string[]

相关数据表的主键。

refresh() 公共 方法

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.

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. Otherwise, this record will remain unchanged.

tableName() 公共 静态 方法

声明与此 AR 类关联的数据库表的名称。 默认情况下,此方法通过使用前缀 yii\db\Connection::$tablePrefix 调用 yii\helpers\Inflector::camel2id() 来返回类名作为表名。 例如,如果 yii\db\Connection::$tablePrefixtbl_, 则 Customer 变为 tbl_customerOrderItem 变为 tbl_order_item 如果未按约定命名表,则可以重写此方法。

public static string tableName()
return string

表名

transactions() 公共 方法

声明应在不同场景的事务中执行那些 DB 操作。 支持的 DB 操作为 OP_INSERTOP_UPDATE 以及 OP_DELETE, 分别对应 insert()update() 以及 delete() 方法, 默认情况下,这些方法不包含在数据库事务中。

在某些情况下,为保持数据一致性, 你可能希望将其中的部分或全部包含在事务中。 你可以通过重写此方法并返回需要进行事务处理的操作来完成此操作。例如,

return [
    'admin' => self::OP_INSERT,
    'api' => self::OP_INSERT | self::OP_UPDATE | self::OP_DELETE,
    // the above is equivalent to the following:
    // 'api' => self::OP_ALL,

];

上述声明指定在 "admin" 场景中, 插入操作 (insert()) 应该在事务中完成; 在 "api" 场景中,所有的操作都应该在事务中完成。

public array transactions()
return array

事务操作声明。数组的键是场景名称, 数组值是相应的事务操作。

update() 公共 方法

将对此活动记录的更改保存到关联的数据库表中。

此方法将按顺序执行一下步骤:

  1. $runValidationtrue 时,调用 beforeValidate()。 如果 beforeValidate() 返回 false,则跳过其余步骤;
  2. $runValidationtrue 时,调用 afterValidate()。 如果验证失败,则跳过其余步骤;
  3. 调用 beforeSave()。如果 beforeSave() 返回 false, 则跳过其余步骤;
  4. 保存记录到数据中。如果保存失败,则跳过余下步骤;
  5. 调用 afterSave()

在上面的步骤1,2,3,以及 5 中, 将通过相应的方法引发事件 EVENT_BEFORE_VALIDATEEVENT_AFTER_VALIDATEEVENT_BEFORE_UPDATE,以及 EVENT_AFTER_UPDATE

只有 changed attribute values 才会保存到数据库。

例如,要更新 customer 记录:

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

注意,更新可能不会影响表中的任何行。 在该情况下,此方法有可能返回 0。 因此,应使用以下代码检查 update() 是否成功:

if ($customer->update() !== false) {
    // update successful
} else {
    // update failed
}
public integer|false update($runValidation true, $attributeNames null)
$runValidation boolean

是否在保存记录之前执行验证 (调用 validate())。 默认为 true,即执行验证。如果验证失败,则记录不会保存到数据库中, 并且此方法将返回 false

$attributeNames array

需要保存的属性列表。 默认为 null,表示将保存从 DB 加载的所有属性。

return integer|false

受影响的行数,如果验证失败或 beforeSave() 停止更新过程, 则为 false。

throws yii\db\StaleObjectException

如果启用了 optimistic locking 并且正在更新的数据已过时,则抛出异常。

throws \Exception|\Throwable

万一更新失败,则抛出异常。

updateAll() 公共 静态 方法

使用提供的属性值和条件更新整个表。

比如,要将所有状态为 2 的客户的状态更改为 1:

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

警告:如果未指定任何条件,则此方法将更新表中的所有行。

注意,此方法不会触发任何事件,如果需要触发 EVENT_BEFORE_UPDATEEVENT_AFTER_UPDATE , 则首先需要 find 模型,然后在每个模型上调用 update()。 例如,下面的例子和前面的例子作用是相同的:

$models = Customer::find()->where('status = 2')->all();
foreach ($models as $model) {
    $model->status = 1;
    $model->update(false); // skipping validation as no user input is involved
}

对于大量模型,可以考虑使用 yii\db\ActiveQuery::each() 将内存使用限制在规定范围内。

public static integer updateAll($attributes, $condition '', $params = [])
$attributes array

要保存在表中的属性值(键值对)

$condition string|array

将放在 UPDATE SQL 的 WHERE 部分中的条件。 有关如何指定此参数,请阅读 yii\db\Query::where()

$params array

要绑定到查询的参数 (name => value)。

return integer

更新的行数

updateAllCounters() 公共 静态 方法

使用提供的计数器更改条件更新整个表。

例如,要将所有客户的年龄增加 1,

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

注意,此方法不会触发任何事件。

public static integer updateAllCounters($counters, $condition '', $params = [])
$counters array

要更新的计数器 (attribute name => increment value)。 如果要递减计数器,请使用负值。

$condition string|array

将放在 UPDATE SQL 的 WHERE 部分中的条件。 有关如何指定此参数,请阅读 yii\db\Query::where()

$params array

要绑定到查询的参数 (name => value)。 不要将参数命名为 :bp0:bp1 等,因为它们是由这个方法内部使用的。

return integer

更新的行数