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
Uses Traitsyii\base\ArrayableTrait, yii\base\StaticInstanceTrait
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/db/ActiveRecord.php

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

Active Record 实现了 Active Record 设计模式. Active Record 的前提是单个 yii\db\ActiveRecord 对象与数据库表中的特定行相关联. 对象的属性映射到相应表的列. 引用 Active Record 属性相当于访问该记录的相应表列.

例如, 假设Customer ActiveRecord 类与customer表相关联. 这意味着该类的name属性会自动映射到customer表中的name列. 得益于 Active Record, 假设变量$customer是类型Customer的对象, 要获取表行的name列的值, 可以使用表达式$customer->name. 在此示例中, Active Record 提供了一个面向对象的接口, 用于访问数据库中存储的数据. 但 Active Record 提供的功能远不止于此.

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

<?php

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

tableName方法仅需要返回与该类关联的数据库表的名称.

Tip: 你也可以使用 Gii代码生成器 从数据库表中生成 ActiveRecord 类.

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

  • 使用new运算符创建一个新的空对象.
  • 使用一种方法从数据库中提取一个或多个现有记录.

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

$user = new User();
$user->name = 'Qiang';
$user->save();  // 在用户表中插入新行

// 以下将从数据库中检索用户'CeBe'
$user = User::find()->where(['name' => 'CeBe'])->one();

// 定义关系后, 将从订单表中获取相关记录
$orders = $user->orders;

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

公共属性

隐藏继承的属性

属性类型描述定义在
$activeValidators yii\validators\Validator[] 适用于当前 场景 的验证器. 该属性是只读的. yii\base\Model
$attributes array 属性值(name => value). yii\base\Model
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$dirtyAttributes array 已更改的属性值(name-value 对). 该属性是只读的. yii\db\BaseActiveRecord
$errors array 所有属性的错误数组. 结果是一个二维数组. 如果没有错误, 则返回空数组. 有关详细说明,请参阅 getErrors(). 该属性是只读的. yii\base\Model
$firstErrors array 第一个错误. 数组键是属性名称, 数组值是对应的错误消息. 如果没有错误, 将返回一个空数组. 该属性是只读的. yii\base\Model
$isNewRecord boolean 记录是否为新记录, 是否应在调用 save() 时插入. yii\db\BaseActiveRecord
$iterator ArrayIterator 用于遍历列表中项目的迭代器. 该属性是只读的. yii\base\Model
$oldAttributes array 旧的属性值(name-value 对). 请注意, 该属性的类型在 getter 和 setter 中有所不同. 有关详细信息, 请参阅 getOldAttributes()setOldAttributes(). yii\db\BaseActiveRecord
$oldPrimaryKey mixed 旧的主键值.如果主键是复合的, 则返回数组(列名=>列值). 否则返回一个字符串(如果键值为空则返回null). 该属性是只读的. yii\db\BaseActiveRecord
$primaryKey mixed 主键值. 如果主键是复合的, 则返回数组(列名=>列值). 否则返回一个字符串(如果键值为空则返回null). 该属性是只读的. yii\db\BaseActiveRecord
$relatedRecords array 由关系名称索引的相关记录的数组. 该属性是只读的. yii\db\BaseActiveRecord
$scenario string 此模型所在的场景. 默认为: SCENARIO_DEFAULT. yii\base\Model
$validators ArrayObject|yii\validators\Validator[] 所有在模型中声明的验证器. 该属性是只读的. yii\base\Model

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\BaseObject
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__unset() 将组件属性设置为null. yii\base\Component
activeAttributes() 返回在当前场景中需要验证的属性名称. yii\base\Model
addError() 向指定的属性添加新的错误. yii\base\Model
addErrors() 添加错误列表. yii\base\Model
afterDelete() 删除记录后调用此方法. yii\db\BaseActiveRecord
afterFind() 当创建 AR 对象并使用查询结果填充该对象时, 将调用此方法. yii\db\BaseActiveRecord
afterRefresh() 刷新 AR 对象后将调用此方法. yii\db\BaseActiveRecord
afterSave() 在插入或更新记录结束时调用此方法. yii\db\BaseActiveRecord
afterValidate() 在验证结束后调用此方法. yii\base\Model
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
attributeHints() 返回属性提示列表. yii\base\Model
attributeLabels() 返回属性标签列表. yii\base\Model
attributes() 返回模型的所有属性名称的列表. yii\db\ActiveRecord
beforeDelete() 在删除记录之前调用此方法. yii\db\BaseActiveRecord
beforeSave() 在插入或更新记录的开始即调用此方法. yii\db\BaseActiveRecord
beforeValidate() 在验证开始之前调用此方法. yii\base\Model
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
className() 返回此类的完全限定名称. yii\base\BaseObject
clearErrors() 删除所有属性或单个属性的错误. yii\base\Model
createValidators() 根据 rules() 中指定的验证规则创建验证器对象. yii\base\Model
delete() 删除与此活动记录对应的表格行. yii\db\ActiveRecord
deleteAll() 使用提供的条件删除表中的行. yii\db\ActiveRecord
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
equals() 返回一个值, 该值指示给定的活动记录是否与当前记录相同. yii\db\ActiveRecord
extraFields() 返回可以进一步扩展并由 toArray() 返回的字段列表. yii\base\ArrayableTrait
fields() 返回未指定任何特定字段时, 默认应由 toArray() 返回的字段列表. 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() 返回此模型类应使用的表单名称. yii\base\Model
generateAttributeLabel() 基于给定的属性名称生成用户友好的属性标签. yii\base\Model
getActiveValidators() 返回适用于当前 场景 的验证器. yii\base\Model
getAttribute() 返回指定的属性值. yii\db\BaseActiveRecord
getAttributeHint() 返回指定属性的文本提示. yii\base\Model
getAttributeLabel() 返回指定属性的文本标签. yii\base\Model
getAttributes() 返回属性值. yii\base\Model
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getDb() 返回此 AR 类使用的数据库连接. yii\db\ActiveRecord
getDirtyAttributes() 返回自最后一次加载或保存以来修改的属性值. yii\db\BaseActiveRecord
getErrorSummary() 将所有属性的错误作为一维数组返回. yii\base\Model
getErrors() 返回所有属性或单个属性的错误. yii\base\Model
getFirstError() 返回指定属性的第一个错误. yii\base\Model
getFirstErrors() 返回模型中每个属性的第一个错误. yii\base\Model
getIsNewRecord() 返回一个值, 指示当前记录是否是新记录. yii\db\BaseActiveRecord
getIterator() 返回用于遍历模型中属性的迭代器. yii\base\Model
getOldAttribute() 返回指定属性的旧值. yii\db\BaseActiveRecord
getOldAttributes() 返回旧的属性值. yii\db\BaseActiveRecord
getOldPrimaryKey() 返回旧的主键值. yii\db\BaseActiveRecord
getPrimaryKey() 返回主键值. yii\db\BaseActiveRecord
getRelatedRecords() 返回所有已填充的相关记录. yii\db\BaseActiveRecord
getRelation() 返回具有指定名称的关系对象. yii\db\BaseActiveRecord
getScenario() 返回此模型使用的场景. yii\base\Model
getTableSchema() 返回与此 AR 类关联的数据库表的模式信息. yii\db\ActiveRecord
getValidators() 返回在 rules() 中声明的所有验证器. yii\base\Model
hasAttribute() 返回一个值, 该值指示模型是否具有指定名称的属性. yii\db\BaseActiveRecord
hasErrors() 返回一个值, 指示是否存在任何验证错误. yii\base\Model
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMany() see yii\db\BaseActiveRecord::hasMany() for more info yii\db\ActiveRecord
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasOne() see yii\db\BaseActiveRecord::hasOne() for more info yii\db\ActiveRecord
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
init() 初始化对象. yii\base\BaseObject
insert() 使用此记录的属性值在关联的数据库表中插入一行. yii\db\ActiveRecord
instance() 返回静态类实例, 该实例可用于获取元信息(meta). yii\base\StaticInstanceTrait
instantiate() 创建活动记录实例. yii\db\BaseActiveRecord
isAttributeActive() 返回一个值, 指示该属性在当前场景中是否处于活动状态. yii\base\Model
isAttributeChanged() 返回一个值, 指示指定的属性是否已更改. yii\db\BaseActiveRecord
isAttributeRequired() 返回一个值, 指示该属性是否是必需的. yii\base\Model
isAttributeSafe() 返回一个值, 指示属性对于大规模分配是否安全. yii\base\Model
isPrimaryKey() 返回一个值, 该值指示给定的属性集是否表示此模型的主键. yii\db\BaseActiveRecord
isRelationPopulated() 检查指定的关系是否已填充记录. yii\db\BaseActiveRecord
isTransactional() 返回一个值, 该值指示指定的操作在当前 场景 中是否是事务性的. yii\db\ActiveRecord
link() 建立两个模型之间的关系. yii\db\BaseActiveRecord
load() 用输入数据填充模型. yii\base\Model
loadDefaultValues() 从数据库表模式加载默认值. yii\db\ActiveRecord
loadMultiple() 使用来自最终用户的数据填充一组模型. yii\base\Model
markAttributeDirty() 销毁旧的属性. yii\db\BaseActiveRecord
off() 从该组件分离现有的事件处理程序. yii\base\Component
offsetExists() 返回指定偏移量处是否有元素. yii\base\Model
offsetGet() 返回指定偏移量处的元素. yii\base\Model
offsetSet() 将元素设置为指定的偏移量. yii\base\Model
offsetUnset() 将指定偏移处的元素值设置为null. yii\base\Model
on() 将事件处理程序附加到事件. yii\base\Component
onUnsafeAttribute() 当大规模(批量)分配不安全属性时, 将调用此方法. yii\base\Model
optimisticLock() Returns the name of the column that stores the lock version for implementing optimistic locking. yii\db\BaseActiveRecord
populateRecord() 使用数据库/存储中的一行数据填充活动的记录对象. yii\db\ActiveRecord
populateRelation() 用相关的记录填充指定的关系. yii\db\BaseActiveRecord
primaryKey() 返回此 AR 类的主键名称. yii\db\ActiveRecord
refresh() 用最新数据重新填充此活动记录. yii\db\ActiveRecord
rules() 返回属性的验证规则. yii\base\Model
safeAttributes() 返回在当前场景中可安全分配的属性名称. yii\base\Model
save() 保存当前记录. yii\db\BaseActiveRecord
scenarios() 返回场景列表和相应的活动属性. yii\base\Model
setAttribute() 设置指定的属性值. yii\db\BaseActiveRecord
setAttributes() 以大规模(批量)的方式设置属性值. yii\base\Model
setIsNewRecord() 设置指示记录是否为新的值. yii\db\BaseActiveRecord
setOldAttribute() 设置指定属性的旧值. yii\db\BaseActiveRecord
setOldAttributes() 设置旧的属性值. yii\db\BaseActiveRecord
setScenario() 设置模型的场景. yii\base\Model
tableName() 声明与此 AR 类关联的数据库表的名称. yii\db\ActiveRecord
toArray() 将模型转换为数组. yii\base\ArrayableTrait
transactions() 声明应在不同情况下在事务中执行哪些数据库操作. yii\db\ActiveRecord
trigger() 触发事件. yii\base\Component
unlink() 销毁两个模型之间的关系. yii\db\BaseActiveRecord
unlinkAll() 销毁当前模型中的关系. yii\db\BaseActiveRecord
update() 将对此活动记录的更改保存到关联的数据库表中. yii\db\ActiveRecord
updateAll() 使用提供的属性值和条件更新整个表. yii\db\ActiveRecord
updateAllCounters() 使用提供的计数器更改和条件更新整个表. yii\db\ActiveRecord
updateAttributes() 更新指定的属性. yii\db\BaseActiveRecord
updateCounters() 更新当前 AR 对象的一个或多个计数器列. yii\db\BaseActiveRecord
validate() 执行数据验证. yii\base\Model
validateMultiple() 验证多个模型. yii\base\Model

受保护的方法

隐藏继承的方法

方法描述定义在
createRelationQuery() has-onehas-many关系创建一个查询实例. yii\db\BaseActiveRecord
deleteInternal() 删除 ActiveRecord 而不考虑事务. yii\db\ActiveRecord
extractFieldsFor() 从给定根字段的字段集合中提取嵌套字段. yii\base\ArrayableTrait
extractRootFields() 从嵌套字段中提取根字段名称. yii\base\ArrayableTrait
filterCondition() 在将数组条件分配给查询过滤器之前对其进行过滤. yii\db\ActiveRecord
filterValidAliases() 返回与表名不同的表别名. yii\db\ActiveRecord
filterValidColumnNames() 有效的列名是表列名或以表名或表别名为前缀的列名. yii\db\ActiveRecord
findByCondition() 根据给定条件查找 ActiveRecord 实例. yii\db\ActiveRecord
insertInternal() 将 ActiveRecord 插入到 DB 中而不考虑事务. yii\db\ActiveRecord
refreshInternal() 使用来自新获取的实例的最新数据重写填充此活动记录. yii\db\BaseActiveRecord
resolveFields() 确定 toArray() 可以返回哪些字段. yii\base\ArrayableTrait
updateInternal() yii\db\BaseActiveRecord

事件

隐藏继承的事件

事件类型描述定义在
EVENT_AFTER_DELETE \yii\db\Event 在记录被删除后触发的事件. yii\db\BaseActiveRecord
EVENT_AFTER_FIND \yii\db\Event 创建记录并使用查询结果填充记录后触发的事件. yii\db\BaseActiveRecord
EVENT_AFTER_INSERT yii\db\AfterSaveEvent 在插入记录后触发的事件. yii\db\BaseActiveRecord
EVENT_AFTER_REFRESH \yii\db\Event 在刷新记录后触发的事件. (available since version 2.0.8) yii\db\BaseActiveRecord
EVENT_AFTER_UPDATE yii\db\AfterSaveEvent 在记录更新后触发的事件. yii\db\BaseActiveRecord
EVENT_AFTER_VALIDATE yii\base\Event validate() 结尾处触发的事件. yii\base\Model
EVENT_BEFORE_DELETE yii\base\ModelEvent 在删除记录之前触发的事件. yii\db\BaseActiveRecord
EVENT_BEFORE_INSERT yii\base\ModelEvent 在插入记录之前触发的事件. yii\db\BaseActiveRecord
EVENT_BEFORE_UPDATE yii\base\ModelEvent 在更新记录之前触发的事件. yii\db\BaseActiveRecord
EVENT_BEFORE_VALIDATE yii\base\ModelEvent validate() 开始时触发的事件. yii\base\Model
EVENT_INIT \yii\db\Event 通过 init() 初始化记录时触发的事件. yii\db\BaseActiveRecord

常量

隐藏继承的常量

常量描述定义在
OP_ALL 7 所有三个操作: 插入, 更新, 删除. 这是表达式的快捷方式: 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' 默认场景的名称. yii\base\Model

方法详情

attributes() public 方法

返回模型的所有属性名称的列表.

默认实现将返回与此 AR 类关联的表的所有列名.

public array attributes ( )
return array

属性名称列表.

delete() public 方法

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

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

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

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

public integer|false delete ( )
return integer|false

删除的行数, 如果由于某种原因删除失败, 则返回false.

Note: 即使删除执行成功, 删除的行数也可能是0.

throws yii\db\StaleObjectException

如果启用 optimistic locking, 并且要删除的数据已过期.

throws \Exception|\Throwable

如果删除失败.

deleteAll() public static 方法

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

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

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

Warning: 如果不指定任何条件, 则此方法将更新表中的所有行.

Note: 此方法将不会触发任何事件. 如果需要触发 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 部分中的条件. 有关如何指定此参数, 请参阅 findOne().

$params array

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

return integer

删除的行数.

deleteInternal() protected 方法

删除 ActiveRecord 而不考虑事务.

protected integer|false deleteInternal ( )
return integer|false

删除的行数, 如果由于某种原因删除失败, 则返回false.

Note: 即使删除执行成功, 删除的行数也可能是0.

throws yii\db\StaleObjectException
equals() public 方法

返回一个值, 该值指示给定的活动记录是否与当前记录相同.

通过比较两个活动记录的表名和主键值进行比较. 如果其中一个记录 is new, 则它们也被视为不相等.

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

要进行比较的记录.

return boolean

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

filterCondition() protected static 方法 (可用自版本: 2.0.15)

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

此方法将确保数组条件仅在现有表列上进行过滤.

protected static array filterCondition ( array $condition, array $aliases = [] )
$condition array

要过滤的条件.

$aliases array
return array

过滤后的条件.

throws yii\base\InvalidArgumentException

如果数组包含不安全的值.

throws yii\base\InvalidConfigException
filterValidAliases() protected static 方法 (可用自版本: 2.0.17)

返回与表名不同的表别名.

protected static array filterValidAliases ( yii\db\Query $query )
$query yii\db\Query
throws yii\base\InvalidConfigException
filterValidColumnNames() protected static 方法 (可用自版本: 2.0.17)

有效的列名是表列名或以表名或表别名为前缀的列名.

protected static array filterValidColumnNames ( $db, array $aliases )
$db yii\db\Connection
$aliases array
throws yii\base\InvalidConfigException
find() public static 方法

创建一个 yii\db\ActiveQueryInterface 实例以进行查询.

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

// 查询ID为1的用户(customer):
$customer = Customer::find()->where(['id' => 1])->one();

// 查询所有活跃的用户(customers), 并按照年龄排序:
$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()
    {
        // 使用 CustomerQuery 代替默认的 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() protected static 方法

根据给定条件查找 ActiveRecord 实例.

findOne()findAll() 在内部调用此方法.

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

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

return yii\db\ActiveQueryInterface

新创建的 ActiveQuery 实例.

throws yii\base\InvalidConfigException

如果未定义主键.

findBySql() public static 方法

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

Note: 因为已经指定了 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() public static 方法

返回此 AR 类使用的数据库连接.

默认情况下, 应用程序db组件用作数据库连接. 如果要使用其它数据库连接, 则可以重写此方法.

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

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

getTableSchema() public static 方法

返回与此 AR 类关联的数据库表的模式信息.

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

与此 AR 类关联的数据库表的模式信息

throws yii\base\InvalidConfigException

如果 AR 类的表不存在.

hasMany() public 方法
public yii\db\ActiveQuery hasMany ( $class, array $link )
$class
$link
return yii\db\ActiveQuery
hasOne() public 方法
public yii\db\ActiveQuery hasOne ( $class, array $link )
$class
$link
return yii\db\ActiveQuery
insert() public 方法

使用此记录的属性值在关联的数据库表中插入一行.

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

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

在上述步骤1,2,3和5中, 将通过相应的方法引发事件 EVENT_BEFORE_VALIDATE, EVENT_AFTER_VALIDATE, EVENT_BEFORE_INSERTEVENT_AFTER_INSERT.

仅将 已更改的属性值 插入到数据库中.

如果表的主键是自动递增的, 并且在插入过程中是null, 则在插入之后将使用实际值填充该表.

例如, 要插入一个客户记录:

$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() protected 方法

将 ActiveRecord 插入到 DB 中而不考虑事务.

protected boolean insertInternal ( $attributes null )
$attributes array

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

return boolean

是否插入成功记录.

isTransactional() public 方法

返回一个值, 该值指示指定的操作在当前 场景 中是否是事务性的.

public boolean isTransactional ( $operation )
$operation integer

要检查的操作. 可能的值包括 OP_INSERT, OP_UPDATEOP_DELETE.

return boolean

指定的操作在当前 场景 中是否是事务性的.

loadDefaultValues() public 方法

从数据库表模式加载默认值.

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

// Customer 类继承自 \yii\db\ActiveRecord
$customer = new Customer();
$customer->loadDefaultValues();
public $this loadDefaultValues ( $skipIfSet true )
$skipIfSet boolean

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

return $this

模型实例本身.

populateRecord() public static 方法

使用数据库/存储中的一行数据填充活动的记录对象.

这是一种内部方法, 在从数据库中获取数据后将被调用以创建活动记录对象. yii\db\ActiveQuery 主要使用它来将查询结果填充到活动记录中.

当手动调用此方法时, 你应该在创建的记录上调用 afterFind() 来触发 afterFind 事件.

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

要填充的记录. 在大多数情况下, 这将是 instantiate() 事先创建的实例.

$row array

属性的值(name => value).

primaryKey() public static 方法

返回此 AR 类的主键名称.

默认实现将返回在与此 AR 类关联的数据库表中声明的主键.

如果数据库表未声明任何主键, 则应重写此方法以返回要用作此 AR 类的主键的属性.

Note: 即使对于具有单个主键的表, 也应返回一个数组.

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

关联数据库表的主键.

refresh() public 方法

用最新数据重新填充此活动记录.

如果刷新成功, 将触发 EVENT_AFTER_REFRESH 事件. 此事件自版本2.0.8起可用.

public boolean refresh ( )
return boolean

该行是否仍存在于数据库中. 如果为true, 则将最新数据填充到此活动记录中. 否则, 此记录将保持不变.

tableName() public static 方法

声明与此 AR 类关联的数据库表的名称.

默认情况下, 此方法通过使用前缀 yii\db\Connection::$tablePrefix 调用 yii\helpers\Inflector::camel2id() 将类名作为表名返回. 例如, 如果 yii\db\Connection::$tablePrefixtbl_, 则Customertbl_customer, OrderItemtbl_order_item. 如果未按照该约定命名表, 则可以重写此方法.

public static string tableName ( )
return string

表名

transactions() public 方法

声明应在不同情况下在事务中执行哪些数据库操作.

支持的数据库操作是 OP_INSERT, OP_UPDATEOP_DELETE, 它们分别对应于 insert(), update()delete() 方法. 默认情况下, 这些方法不包含在数据库事务中.

在某些情况下, 为确保数据一致性, 你可能需要将其中的一些或全部放入事务中. 你可以通过重写此方法并返回需要进行事务处理的操作来实现该需求. 例如:

return [
    'admin' => self::OP_INSERT,
    'api' => self::OP_INSERT | self::OP_UPDATE | self::OP_DELETE,
    // 以上相当于以下内容:
    // 'api' => self::OP_ALL,

];

上面的声明指定在"admin"场景中, 插入操作 应该在事务中完成; 而在"api"情景中, 所有的操作都应在事务中完成.

public array transactions ( )
return array

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

update() public 方法

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

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

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

在上述步骤1,2,3和5中, 将通过相应的方法引发事件 EVENT_BEFORE_VALIDATE, EVENT_AFTER_VALIDATE, EVENT_BEFORE_UPDATEEVENT_AFTER_UPDATE.

仅将 已更改的属性值 保存到数据库中.

例如, 要更新客户记录:

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

Note: 更新可能不会影响表中的任何行. 在这种情况下, 此方法将返回0. 因此, 你应使用以下代码检查 update() 是否成功:

if ($customer->update() !== false) {
    // 更新成功
} else {
    // 更新失败
}
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() public static 方法

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

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

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

Warning: 如果不指定任何条件, 则此方法将更新表中的所有行.

Note: 此方法将不会触发任何事件. 如果需要触发 EVENT_BEFORE_UPDATEEVENT_AFTER_UPDATE, 则需要先 find 每个模型, 然后在每个模型上分别调用 update(). 例如, 上面的例子相当于:

$models = Customer::find()->where('status = 2')->all();
foreach ($models as $model) {
    $model->status = 1;
    $model->update(false); // 由于不涉及用户输入而跳过验证
}

对于大量的模型, 你可以考虑使用 yii\db\ActiveQuery::each() 将内存使用保持在限制范围内.

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

要保存到表中的属性值(name-value 对).

$condition string|array

将放在 UPDATE SQL 的 WHERE 部分中的条件. 有关如何指定此参数, 请参阅 findOne().

$params array

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

return integer

更新的行数.

updateAllCounters() public static 方法

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

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

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

Note: 此方法将不会触发任何事件.

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

要更新的计数器(属性名称=>增量值). 如果要减少计数器, 请使用负值.

$condition string|array

将放在 UPDATE SQL 的 WHERE 部分中的条件. 有关如何指定此参数, 请参阅 findOne().

$params array

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

return integer

更新的行数.