没有命名空间的类 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

Interface yii\db\ActiveRecordInterface

继承yii\base\StaticInstanceInterface
实现yii\db\ActiveRecord, yii\db\BaseActiveRecord
可用版本自2.0
源码 https://github.com/yiichina/yii2/blob/api/framework/db/ActiveRecordInterface.php

ActiveRecordInterface.

公共方法

隐藏继承的方法

方法描述被定义在
attributes() 返回记录的所有属性列表名称。 yii\db\ActiveRecordInterface
delete() 从数据库删除记录。 yii\db\ActiveRecordInterface
deleteAll() 使用提供的条件删除记录。 WARNING:如果未指定任何条件,则此方法将删除表中的所有行。 yii\db\ActiveRecordInterface
equals() 返回一个表示给定的记录是否与当前记录相同的值。 两个 new 记录被认为是不相等的。 yii\db\ActiveRecordInterface
find() 创建用来查询的 yii\db\ActiveQueryInterface 实例。 yii\db\ActiveRecordInterface
findAll() 返回与指定的主键值或一组列值匹配的活动记录模型的列表。 yii\db\ActiveRecordInterface
findOne() 通过主键或列值数组返回单个活动记录模型实例。 yii\db\ActiveRecordInterface
getAttribute() 返回指定的属性值。 如果此记录是查询的结果并且未加载该属性, 将会返回 null yii\db\ActiveRecordInterface
getDb() 返回此 AR 类使用的连接。 yii\db\ActiveRecordInterface
getIsNewRecord() 返回一个表示当前记录是否为新纪录的值(未保存在数据库中)。 yii\db\ActiveRecordInterface
getOldPrimaryKey() 返回旧的主键值。 这是指在执行 find 方法, (例如 find(),findOne())后填充到记录中的主键值。 即使主键属性是手动指定的不同的值,该值仍然保持不变。 yii\db\ActiveRecordInterface
getPrimaryKey() 返回主键的值。 yii\db\ActiveRecordInterface
getRelation() 返回具有指定名称的关系对象。 关系由 getter 方法定义, 该方法返回实现 yii\db\ActiveQueryInterface 的对象(通常这将是 yii\db\ActiveQuery 对象)。 它可以在 ActiveRecord 类本身或其行为之一中申明。 yii\db\ActiveRecordInterface
hasAttribute() 返回一个值,表示记录是否具有指定名称的属性。 yii\db\ActiveRecordInterface
insert() 使用此记录的属性值将记录插入数据库。 yii\db\ActiveRecordInterface
instance() 返回静态类实例,可用于获取 meta 信息。 yii\base\StaticInstanceInterface
isPrimaryKey() 返回一个表明给定的属性集是否是该模型的主键的值。 yii\db\ActiveRecordInterface
link() 建立两条记录之间的关系。 yii\db\ActiveRecordInterface
populateRelation() 使用相关记录填充命名关系。 注意,此方法不会检查关系是否存在。 yii\db\ActiveRecordInterface
primaryKey() 返回此 AR 类的主键 name(s) yii\db\ActiveRecordInterface
save() 保存当前记录。 yii\db\ActiveRecordInterface
setAttribute() 设置指定的属性值。 yii\db\ActiveRecordInterface
unlink() 破坏两条记录之间的关系。 yii\db\ActiveRecordInterface
update() 将对此活动记录的更改保存到数据库中。 yii\db\ActiveRecordInterface
updateAll() 使用提供的属性值和条件更新记录。 yii\db\ActiveRecordInterface

方法详情

attributes() 公共 抽象 方法

返回记录的所有属性列表名称。

public abstract array attributes()
return array

属性名称列表。

delete() 公共 抽象 方法

从数据库删除记录。

public abstract integer|boolean delete()
return integer|boolean

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

deleteAll() 公共 抽象 静态 方法

使用提供的条件删除记录。 WARNING:如果未指定任何条件,则此方法将删除表中的所有行。

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

Customer::deleteAll([status = 3]);
public abstract static integer deleteAll($condition null)
$condition array

与应删除的记录匹配的条件。 有关于如果指定参数,请参阅 yii\db\QueryInterface::where()。 空条件将匹配所有记录。

return integer

The number of rows deleted

equals() 公共 抽象 方法

返回一个表示给定的记录是否与当前记录相同的值。 两个 new 记录被认为是不相等的。

public abstract boolean equals($record)
$record static

要比较的记录

return boolean

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

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 abstract static yii\db\ActiveQueryInterface find()
return yii\db\ActiveQueryInterface

新创建的 yii\db\ActiveQueryInterface 实例。

findAll() 公共 抽象 静态 方法

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

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'));
public abstract static array findAll($condition)
$condition mixed

主键值或一组列值

return array

一个 ActiveRecord 实例数组,如果没有匹配则为空数组。

findOne() 公共 抽象 静态 方法

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

该方法接受:

  • 标量值(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'));
public abstract static static findOne($condition)
$condition mixed

主键值或一组列值。

return static

与条件匹配的 ActiveRecord 实例,如果没有匹配则为 null

getAttribute() 公共 抽象 方法

返回指定的属性值。 如果此记录是查询的结果并且未加载该属性, 将会返回 null

参见 hasAttribute().

public abstract mixed getAttribute($name)
$name string

属性名

return mixed

属性值。如果属性未设置或者不存在,返回 null

getDb() 公共 抽象 静态 方法

返回此 AR 类使用的连接。

public abstract static mixed getDb()
return mixed

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

getIsNewRecord() 公共 抽象 方法

返回一个表示当前记录是否为新纪录的值(未保存在数据库中)。

public abstract boolean getIsNewRecord()
return boolean

是否记录是新的,应在调用 save() 时插入。

getOldPrimaryKey() 公共 抽象 方法

返回旧的主键值。 这是指在执行 find 方法, (例如 find(),findOne())后填充到记录中的主键值。 即使主键属性是手动指定的不同的值,该值仍然保持不变。

public abstract mixed getOldPrimaryKey($asArray false)
$asArray boolean

是否将主键值作为一个数组返回。 如果为 true,返回值将是一个数组,属性名称为键,属性值为值。 如果为 false(默认值),将为非复合主键返回标量值。

return mixed

旧的主键值。 如果主键是复合键或 $asArray 为 true,则返回数组(column name => column value)。 否则将返回一个字符串(如果键值为 null,则返回 null)。

getPrimaryKey() 公共 抽象 方法

返回主键的值。

public abstract mixed getPrimaryKey($asArray false)
$asArray boolean

是否将主键值作为数组返回。 如果为 true,返回值将是一个数组,属性名称为键,属性值为值。 请注意,对于复合主键,无论此参数值如何,都将始终返回一个数组。

return mixed

主键值。如果主键是复合键或 $asArray 为 true, 则返回数组(attribute name => attribute value)。 否则返回一个字符串(如果键值为 null,则返回 null)。

getRelation() 公共 抽象 方法

返回具有指定名称的关系对象。 关系由 getter 方法定义, 该方法返回实现 yii\db\ActiveQueryInterface 的对象(通常这将是 yii\db\ActiveQuery 对象)。 它可以在 ActiveRecord 类本身或其行为之一中申明。

public abstract yii\db\ActiveQueryInterface getRelation($name, $throwException true)
$name string

关系名称,例如 orders 用于通过 getOrders() 方法定义的关系(区分大小写)。

$throwException boolean

如果关系不存在,是否抛出异常。

return yii\db\ActiveQueryInterface

关系查询对象

hasAttribute() 公共 抽象 方法

返回一个值,表示记录是否具有指定名称的属性。

public abstract boolean hasAttribute($name)
$name string

属性名

return boolean

记录是否具有指定名称的属性。

insert() 公共 抽象 方法

使用此记录的属性值将记录插入数据库。

用法示例:

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

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

$attributes array

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

return boolean

属性是否有效并且记录是否已成功插入。

isPrimaryKey() 公共 抽象 静态 方法

返回一个表明给定的属性集是否是该模型的主键的值。

public abstract static boolean isPrimaryKey($keys)
$keys array

要检查的属性集

return boolean

给定的属性集是否是此模型的主键

link() 公共 抽象 方法

建立两条记录之间的关系。

通过将一个记录中的外键值设置为另外一个记录中相应的主键值, 从而建立该关系。 具有外键的记录将被保存到数据库中而不进行验证。

如果这个关系涉及到一个连接表, 那么一个新的行将被插入到包含来自两个记录的主键值的连接表中。

方法要求主键值不能为 null

public abstract void link($name, $model, $extraColumns = [])
$name string

区分大小写的关系名称,例如 orders 用于通过 getOrders() 方法定义的关系。

$model static

与当前记录链接的记录。

$extraColumns array

要保存的连接表中的附加列值。 此参数仅对涉及连接表的关系(即, 使用 yii\db\ActiveQueryInterface::via() 设置的关系)有意义。

populateRelation() 公共 抽象 方法 (自版本 2.0.8 可用)

使用相关记录填充命名关系。 注意,此方法不会检查关系是否存在。

public abstract void populateRelation($name, $records)
$name string

关系名称,例如 orders 用于通过 getOrders() 方法定义的关系(区分大小写)。

$records yii\db\ActiveRecordInterface|array|null

要填充到关系中的相关记录。

primaryKey() 公共 抽象 静态 方法

返回此 AR 类的主键 name(s)

注意,即使记录只有一个主键,也应该返回一个数组。

对于主键 value 请参阅 getPrimaryKey()

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

此 AR 类的主键名称。

save() 公共 抽象 方法

保存当前记录。

isNewRecord 为 true 时,将调用 insert(), 当 isNewRecord 为 false 时,将调用 update()

例如,要保存客户记录:

$customer = new Customer; // or $customer = Customer::findOne($id);
$customer->name = $name;
$customer->email = $email;
$customer->save();
public abstract boolean save($runValidation true, $attributeNames null)
$runValidation boolean

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

$attributeNames array

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

return boolean

是否保存成功(即没有发生验证错误)。

setAttribute() 公共 抽象 方法

设置指定的属性值。

参见 hasAttribute().

public abstract void setAttribute($name, $value)
$name string

属性名。

$value mixed

属性值。

unlink() 公共 抽象 方法

破坏两条记录之间的关系。

如果 $delete 为真,则删除具有关系外键的记录。 否则,外键将被设置为 null,并且将保存记录而不进行验证。

public abstract void unlink($name, $model, $delete false)
$name string

区分大小写的关系名称,例如 orders 用于通过 getOrders() 方法定义的关系。

$model static

该模型与当前模型无关。

$delete boolean

是否删除包含外键的模型。 如果为 false,模型的外键将设置为 null 并保存。 如果为 true,包含外键的模型将被删除。

update() 公共 抽象 方法

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

用法示例:

$customer = Customer::findOne($id);
$customer->name = $name;
$customer->email = $email;
$customer->update();
public abstract integer|boolean update($runValidation true, $attributeNames null)
$runValidation boolean

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

$attributeNames array

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

return integer|boolean

影响的行数, 如果验证失败或者由于其他原因停止更新过程,返回 false。 注意,即使更新成功, 受影响的行数也有可能为 0。

updateAll() 公共 抽象 静态 方法

使用提供的属性值和条件更新记录。

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

Customer::updateAll(['status' => 1], ['status' => '2']);
public abstract static integer updateAll($attributes, $condition null)
$attributes array

要为记录保存的属性值(键值对)。 与 update() 不同,这些不会被验证。

$condition array

与应更新的记录匹配的条件。 有关于如何指定此参数,请参阅 yii\db\QueryInterface::where()。 空条件将匹配所有记录。

return integer

更新的行数