Interface yii\db\ActiveRecordInterface

扩展yii\base\StaticInstanceInterface
Implemented byyii\db\ActiveRecord, yii\db\BaseActiveRecord
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/db/ActiveRecordInterface.php

ActiveRecordInterface(ActiveRecord 接口).

公共方法

隐藏继承的方法

方法描述定义在
attributes() 返回记录的所有属性名称的列表. yii\db\ActiveRecordInterface
delete() 从数据库中删除记录. yii\db\ActiveRecordInterface
deleteAll() 使用提供的条件删除记录. yii\db\ActiveRecordInterface
equals() 返回一个值, 指示给定的活动记录是否与当前活动记录相同. yii\db\ActiveRecordInterface
find() 创建一个 yii\db\ActiveQueryInterface 实例以进行查询. yii\db\ActiveRecordInterface
findAll() 返回与指定的主键值或一组列值匹配的活动记录模型的列表. yii\db\ActiveRecordInterface
findOne() 通过主键或列值的数组返回单个活动记录模型实例. yii\db\ActiveRecordInterface
getAttribute() 返回指定的属性值. yii\db\ActiveRecordInterface
getDb() 返回此 AR 类使用的连接. yii\db\ActiveRecordInterface
getIsNewRecord() 返回一个值, 表示当前记录是否为新记录(未保存在数据库中). yii\db\ActiveRecordInterface
getOldPrimaryKey() 返回旧的主键值. yii\db\ActiveRecordInterface
getPrimaryKey() 返回主键值. yii\db\ActiveRecordInterface
getRelation() 返回具有指定名称的关系对象. 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 类的主键名称. 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 方法

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

public abstract array attributes ( )
return array

属性名称列表.

delete() public abstract 方法

从数据库中删除记录.

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

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

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

deleteAll() public abstract static 方法

使用提供的条件删除记录.

Warning: 如果不指定任何条件, 该方法将删除表中的所有行.

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

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

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

return integer

删除的行数.

equals() public abstract 方法

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

两个 new 记录被认为是不相等的.

public abstract boolean equals ( $record )
$record static

要比较的记录.

return boolean

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

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

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

findAll() public abstract static 方法

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

该方法接收:

  • 标量值(整数或字符串): 通过单个主键值查询并返回包含相应记录的数组(如果未找到, 则返回空数组).
  • 非关联数组: 通过主键值列表进行查询并返回相应的记录(如果未找到, 则返回空数组).

    Note: 空条件将导致空结果, 因为它将被解释为对主键的搜索而不是空的WHERE条件.

  • name-value 对的关联数组: 按一组属性值查询并返回与所有属性值匹配的记录的数组(如果未找到, 则返回空数组). 请注意['id' => 1, 2]被视为非关联数组. 列名仅限于 SQL DBMS 的当前记录表列, 或者进行过滤以限制为简单过滤条件.
  • a yii\db\Expression: 该表达式将直接使用. (@since 2.0.37)

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

Note: 由于这只是一个简写方法, 因此无法使用更复杂的条件, 例如['!=', 'id', 1]. 如果需要指定更复杂的条件, 请与 where() 结合使用 find().

有关用法示例, 请参阅以下代码:

// 查询主键值为10的用户(customers):
$customers = Customer::findAll(10);

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

// 查询主键值为10,11或12的用户(customers):
$customers = Customer::findAll([10, 11, 12]);

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

// 查询年龄为30岁, status为1的用户(customers):
$customers = Customer::findAll(['age' => 30, 'status' => 1]);

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

如果需要将用户输入传递给此方法, 请确保输入值为标量, 或在数组条件下, 请确保不能从外部更改数组结构:

// yii\web\Controller 确保 $id 为标量值
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() public abstract static 方法

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

该方法接收:

  • 标量值(整数或字符串): 通过单个主键值查询并返回相应的记录(如果未找到则为null).
  • 非关联数组: 通过主键值列表进行查询并返回第一条记录(如果未找到则为null).
  • name-value 对的关联数组: 按一组属性值进行查询, 并返回与所有属性值匹配的单个记录(如果未找到则为null). 请注意, ['id' => 1, 2]被视为非关联数组.
  • a yii\db\Expression: 该表达式将直接使用. (@since 2.0.37)

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

Note: 由于这只是一个简写方法, 因此无法使用更复杂的条件, 例如['!=', 'id', 1]. 如果需要指定更复杂的条件, 请与 where() 结合使用 find().

有关用法示例, 请参阅以下代码:

// 查询主键值为10的单个用户(customer):
$customer = Customer::findOne(10);

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

// 查询主键值为10,11或12的用户(customers):
$customers = Customer::findOne([10, 11, 12]);

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

// 查询年龄为30岁, status为1的第一个用户(customer):
$customer = Customer::findOne(['age' => 30, 'status' => 1]);

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

如果需要将用户输入传递给此方法, 请确保输入值为标量, 或在数组条件下, 请确保不能从外部更改数组结构:

// yii\web\Controller 确保 $id 为标量值
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|null findOne ( $condition )
$condition mixed

主键值或一组列值.

return static|null

符合条件的 ActiveRecord 实例, 如果没有匹配项, 则为null.

getAttribute() public abstract 方法

返回指定的属性值.

如果此记录是查询的结果, 并且属性未加载, 则将返回null.

参见 hasAttribute().

public abstract mixed getAttribute ( $name )
$name string

属性名称.

return mixed

属性值. 如果属性未设置或不存在, 则为null.

getDb() public abstract static 方法

返回此 AR 类使用的连接.

public abstract static mixed getDb ( )
return mixed

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

getIsNewRecord() public abstract 方法

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

public abstract boolean getIsNewRecord ( )
return boolean

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

getOldPrimaryKey() public abstract 方法

返回旧的主键值.

这是指执行 find 方法(eg. find(), findOne())后填充到记录中的主键值. 即使手动为主键属性分配了不同的值, 该值仍保持不变.

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

是否以数组形式返回主键值. 如果为true, 则返回值将是一个数组, 其列名称作为键, 列值作为值. 如果为false(默认值), 则将为非复合主键返回一个标量值.

return mixed

主键值. 如果主键是复合键或$asArraytrue, 则返回数组(属性名=>属性值). 否则返回一个字符串(如果键值为空, 则返回null).

getPrimaryKey() public abstract 方法

返回主键值.

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

是否以数组形式返回主键值. 如果为true, 则返回值将是一个数组, 其属性名称作为键, 属性值作为值.

Note: 对于复合主键, 无论此参数值如何, 都将始终返回数组.

return mixed

主键值. 如果主键是复合键或$asArraytrue, 则返回数组(属性名=>属性值). 否则返回一个字符串(如果键值为空, 则返回null).

getRelation() public abstract 方法

返回具有指定名称的关系对象.

通过 getter 方法定义一个关系, 该方法将返回一个实现 yii\db\ActiveQueryInterface 的对象(通常这是一个关系 yii\db\ActiveQuery 对象). 可以在 ActiveRecord 类本身或其行为之一中声明.

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

关系名称(区分大小写), eg. 通过getOrders()方法定义的关系orders.

$throwException boolean

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

return yii\db\ActiveQueryInterface

关系查询对象.

hasAttribute() public abstract 方法

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

public abstract boolean hasAttribute ( $name )
$name string

属性的名称.

return boolean

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

insert() public abstract 方法

使用该记录的属性值将记录插入数据库.

用法示例:

$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 方法

返回一个值, 指示给定的属性集是否表示该模型的主键.

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

要检查的属性集.

return boolean

给定的属性集是否表示该模型的主键.

link() public abstract 方法

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

通过将一个记录中的外键值设置为另一记录中的对应主键值来建立关系. 使用外键的记录将保存到数据库中, 而无需执行验证.

如果关系涉及连接表, 则将在连接表中插入一个新行, 其中包含来自两个记录的主键值.

该方法要求主键值不为null.

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

关系名称(区分大小写), eg. 通过getOrders()方法定义的关系orders.

$model static

与当前记录关联的记录.

$extraColumns array

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

populateRelation() public abstract 方法 (可用自版本: 2.0.8)

与相关记录填充的指定关系.

Note: 此方法不检查关系是否存在.

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

关系名称(区分大小写), eg. 通过getOrders()方法定义的关系orders.

$records yii\db\ActiveRecordInterface|array|null

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

primaryKey() public abstract static 方法

返回此 AR 类的主键名称.

Note: 即使记录只有一个主键, 也应返回一个数组.

有关主键值的信息, 请参阅 getPrimaryKey().

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

此 AR 类的主键名称.

save() public abstract 方法

保存当前记录.

如果 isNewRecordtrue, 则此方法将调用 insert(); 如果 isNewRecordfalse, 则此方法将调用 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() public abstract 方法

设置指定属性的值.

参见 hasAttribute().

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

属性名称.

$value mixed

属性值.

unlink() public abstract 方法

销毁两条记录之间的关系.

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

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

区分大小写的关系名称. eg. 通过getOrders()方法定义的关系的orders.

$model static

与当前模型取消关联的模型.

$delete boolean

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

update() public abstract 方法

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

用法示例:

$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.

Note: 即使更新执行成功, 受影响的行数也可能为0.

updateAll() public abstract static 方法

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

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

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

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

$condition mixed

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

return integer

更新的行数.