Trait yii\db\QueryTrait

Implemented byyii\db\ActiveQuery, yii\db\Query
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/db/QueryTrait.php

BaseQuery trait 表示数据库 Query 的最小方法集.

应该在实现 yii\db\QueryInterface 的类中使用它.

公共属性

隐藏继承的属性

属性类型描述定义在
$emulateExecution boolean 是否模拟实际的查询执行, 返回空或者false结果. yii\db\QueryTrait
$indexBy string|callable 查询结果所依据的列的名称. yii\db\QueryTrait
$limit integer|yii\db\ExpressionInterface 返回的最大记录数. yii\db\QueryTrait
$offset integer|yii\db\ExpressionInterface 0开始的记录偏移量. yii\db\QueryTrait
$orderBy array 如何对查询结果进行排序. yii\db\QueryTrait
$where string|array|yii\db\ExpressionInterface 查询条件. yii\db\QueryTrait

公共方法

隐藏继承的方法

方法描述定义在
addOrderBy() 将其它 ORDER BY 列添加到查询中. yii\db\QueryTrait
andFilterWhere() 将一个 WHERE 条件添加到现有条件中, 但忽略 空操作数. yii\db\QueryTrait
andWhere() 将一个 WHERE 条件添加到现有条件中. yii\db\QueryTrait
emulateExecution() 设置是否模拟查询执行, 以防止与数据存储的任何交互. yii\db\QueryTrait
filterWhere() 设置查询的 WHERE 部分, 但忽略 空操作数. yii\db\QueryTrait
indexBy() 设置 indexBy() 属性. yii\db\QueryTrait
limit() 设置查询的 LIMIT 部分. yii\db\QueryTrait
offset() 设置查询的 OFFSET 部分. yii\db\QueryTrait
orFilterWhere() 将一个 WHERE 条件添加到现有条件中, 但忽略 空操作数. yii\db\QueryTrait
orWhere() 将一个 WHERE 条件添加到现有条件中. yii\db\QueryTrait
orderBy() 设置查询的 ORDER BY 部分. yii\db\QueryTrait
where() 设置查询的 WHERE 部分. yii\db\QueryTrait

受保护的方法

隐藏继承的方法

方法描述定义在
filterCondition() 从给定的查询条件中移除 空的操作数. yii\db\QueryTrait
isEmpty() 判断给定值是否为. yii\db\QueryTrait
normalizeOrderBy() 规范 ORDER BY 数据的格式. yii\db\QueryTrait

属性详情

$emulateExecution public 属性 (可用自版本: 2.0.11)

是否模拟实际的查询执行, 返回空或者false结果.

参见 emulateExecution().

public boolean $emulateExecution false
$indexBy public 属性

查询结果所依据的列的名称. 这也可以是可调用的(eg. 匿名函数), 该调用基于给定的行数据返回索引值. 有关更多详细信息, 请参阅 indexBy(). 该属性仅由 all() 使用.

public string|callable $indexBy null
$limit public 属性

返回的最大记录数. 可能是 yii\db\ExpressionInterface 的一个实例. 如果未设置或小于0, 则表示没有限制.

$offset public 属性

0开始的记录偏移量. 可能是 yii\db\ExpressionInterface 的一个实例. 如果未设置或小于0, 则表示从头开始.

$orderBy public 属性

如何对查询结果进行排序. 这用于在 SQL 语句中构造 ORDER BY 子句. 数组键是要排序的列, 数组值是相应的排序方向, 可以是 SORT_ASCSORT_DESC. 该数组还可能包含 yii\db\ExpressionInterface 对象. 在这种情况下, 表达式将被转换为字符串, 而无需进行任何更改.

public array $orderBy null
$where public 属性

查询条件. 这是指 SQL 语句中的 WHERE 子句. 例如, ['age' => 31, 'team' => 1].

参见 where() 有关指定此值的有效语法.

方法详情

addOrderBy() public 方法

将其它 ORDER BY 列添加到查询中.

参见 orderBy().

public $this addOrderBy ( $columns )
$columns string|array|yii\db\ExpressionInterface

要排序的列(和方向). 列可以用字符串(eg. "id ASC, name DESC")或数组(eg. ['id' => SORT_ASC, 'name' => SORT_DESC])指定. 除非该列中包含一些括号(表示该列包含一个 DB 表达式), 否则该方法将自动引用该列的名称.

Note: 如果你的 order-by 是一个包含逗号的表达式, 则应始终使用数组来表示 order-by 信息. 否则, 该方法将无法正确确定 order-by 列.

从版本2.0.7开始, 可以传递一个 yii\db\Expression 对象以在普通 SQL 中显示指定 ORDER BY 部分.

return $this

查询对象本身.

andFilterWhere() public 方法

将一个 WHERE 条件添加到现有条件中, 但忽略 空操作数.

新条件和现有条件将使用AND运算符合并.

此方法类似于 andWhere(). 主要区别在于此方法将删除 空的查询操作数. 因此, 此方法最适合基于用户输入的过滤器值构建查询条件.

参见:

public $this andFilterWhere ( array $condition )
$condition array

新的 WHERE 条件. 有关如何指定此参数, 请参考 where().

return $this

查询对象本身.

andWhere() public 方法

将一个 WHERE 条件添加到现有条件中.

新条件和现有条件将使用AND运算符合并.

参见:

public $this andWhere ( $condition )
$condition string|array|yii\db\ExpressionInterface

新的 WHERE 条件. 有关如何指定此参数, 请参考 where().

return $this

查询对象本身.

emulateExecution() public 方法 (可用自版本: 2.0.11)

设置是否模拟查询执行, 以防止与数据存储的任何交互.

启用此模式后, 诸如 yii\db\QueryInterface::one(), yii\db\QueryInterface::all(), yii\db\QueryInterface::exists() 等查询结果的方法将返回空值或false值. 如果你的程序逻辑指示查询不应返回任何结果, 则应使用此方法, 例如在条件0=1的情况下设置为false.

public $this emulateExecution ( $value true )
$value boolean

是否阻止查询执行.

return $this

查询对象本身.

filterCondition() protected 方法

从给定的查询条件中移除 空的操作数.

protected array filterCondition ( $condition )
$condition array

原始的条件.

return array

被删除 空的操作数 后的条件.

throws yii\base\NotSupportedException

如果不支持条件运算符.

filterWhere() public 方法

设置查询的 WHERE 部分, 但忽略 空操作数.

该方法类似于 where(). 主要区别在于此方法将删除 空的查询操作. 因此, 此方法最适合基于用户输入的过滤器值构建查询条件.

以下代码显示了此方法与 where() 之间的区别:

// WHERE `age`=:age
$query->filterWhere(['name' => null, 'age' => 20]);
// WHERE `age`=:age
$query->where(['age' => 20]);
// WHERE `name` IS NULL AND `age`=:age
$query->where(['name' => null, 'age' => 20]);

Note: where() 不同, 你不能将绑定参数传递给此方法.

参见:

public $this filterWhere ( array $condition )
$condition array

应该放在 WHERE 部分的条件. 有关如何指定此参数, 请参考 where().

return $this

查询对象本身.

indexBy() public 方法

设置 indexBy() 属性.

public $this indexBy ( $column )
$column string|callable

查询结果所依据的列的名称. 这也可以是可调用的(eg. 例如匿名函数), 该调用基于给定的行数据返回索引值. 可调用对象的签名应该是:

function ($row)
{
    // 返回对应于 $row 的索引值
}
return $this

查询对象本身.

isEmpty() protected 方法

判断给定值是否为.

如果满足以下条件之一, 则将该值视为:

  • null,
  • 一个空字符串 (''),
  • 一个只包含空白字符串的字符串,
  • 一个空数组.
protected boolean isEmpty ( $value )
$value mixed
return boolean

该值是否为.

limit() public 方法

设置查询的 LIMIT 部分.

public $this limit ( $limit )
$limit integer|yii\db\ExpressionInterface|null

限制. 使用null或负值来禁用限制.

return $this

查询对象本身.

normalizeOrderBy() protected 方法

规范 ORDER BY 数据的格式.

protected array normalizeOrderBy ( $columns )
$columns array|string|yii\db\ExpressionInterface

要进行标准化的列值. 请参阅 orderBy()addOrderBy().

offset() public 方法

设置查询的 OFFSET 部分.

public $this offset ( $offset )
$offset integer|yii\db\ExpressionInterface|null

偏移量. 使用null或负值来禁用偏移.

return $this

查询对象本身.

orFilterWhere() public 方法

将一个 WHERE 条件添加到现有条件中, 但忽略 空操作数.

新条件和现有条件将使用OR运算符合并.

此方法类似于 orWhere(). 主要区别在于此方法将删除 空的查询操作数. 因此, 此方法最适合基于用户输入的过滤器值构建查询条件.

参见:

public $this orFilterWhere ( array $condition )
$condition array

新的 WHERE 条件. 有关如何指定此参数, 请参考 where().

return $this

查询对象本身.

orWhere() public 方法

将一个 WHERE 条件添加到现有条件中.

新条件和现有条件将使用OR运算符合并.

参见:

public $this orWhere ( $condition )
$condition string|array|yii\db\ExpressionInterface

新的 WHERE 条件. 有关如何指定此参数, 请参考 where().

return $this

查询对象本身.

orderBy() public 方法

设置查询的 ORDER BY 部分.

参见 addOrderBy().

public $this orderBy ( $columns )
$columns string|array|yii\db\ExpressionInterface

要排序的列(和方向). 列可以用字符串(eg. "id ASC, name DESC")或数组(eg. ['id' => SORT_ASC, 'name' => SORT_DESC])指定. 除非该列中包含一些括号(表示该列包含一个 DB 表达式), 否则该方法将自动引用该列的名称.

Note: 如果你的 order-by 是一个包含逗号的表达式, 则应始终使用数组来表示 order-by 信息. 否则, 该方法将无法正确确定 order-by 列.

从版本2.0.7开始, 可以传递一个 yii\db\ExpressionInterface 对象以在普通 SQL 中显示指定 ORDER BY 部分.

return $this

查询对象本身.

where() public 方法

设置查询的 WHERE 部分.

有关详细的文档, 请参阅 yii\db\QueryInterface::where().

参见:

public $this where ( $condition )
$condition string|array|yii\db\ExpressionInterface

应该放在 WHERE 部分的条件.

return $this

查询对象本身.