0 关注者

Trait yii\db\QueryTrait

所有类 | 属性 | 方法
实现于yii\db\ActiveQuery, yii\db\Query
可用版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/db/QueryTrait.php

BaseQuery 特性表示数据库查询的最小方法集。

它应该用于实现 yii\db\QueryInterface 的类中。

公共属性

隐藏继承的属性

属性 类型 描述 定义于
$emulateExecution boolean 是否模拟实际查询执行，返回空或假结果。 yii\db\QueryTrait
$indexBy string|callable|null 查询结果应该按哪个列索引。 yii\db\QueryTrait
$limit integer|yii\db\ExpressionInterface|null 要返回的最大记录数。 yii\db\QueryTrait
$offset integer|yii\db\ExpressionInterface|null 从哪里开始返回记录的零基偏移量。 yii\db\QueryTrait
$orderBy array|null 如何对查询结果排序。 yii\db\QueryTrait
$where string|array|yii\db\ExpressionInterface|null 查询条件。 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 公共属性 (自版本 2.0.11 起可用)

是否模拟实际查询执行，返回空或假结果。

另请参阅 emulateExecution()。

public boolean $emulateExecution = false
$indexBy 公共属性

查询结果应该按哪个列索引。这也可以是一个可调用对象（例如匿名函数），它根据给定的行数据返回索引值。有关更多详细信息，请参阅 indexBy()。此属性仅由 all() 使用。

public string|callable|null $indexBy = null
$limit 公共属性

要返回的最大记录数。可以是 yii\db\ExpressionInterface 的实例。如果未设置或小于 0，则表示没有限制。

public integer|yii\db\ExpressionInterface|null $limit = null
$offset 公共属性

从哪里开始返回记录的零基偏移量。可以是 yii\db\ExpressionInterface 的实例。如果未设置或小于 0，则表示从开头开始。

public integer|yii\db\ExpressionInterface|null $offset = null
$orderBy 公共属性

如何排序查询结果。这用于构建 SQL 语句中的 ORDER BY 子句。数组键是要排序的列，数组值是相应的排序方向，可以是 SORT_ASC 或 SORT_DESC。数组也可以包含 yii\db\ExpressionInterface 对象。如果是这种情况，表达式将转换为字符串而无需任何更改。

public array|null $orderBy = null
$where 公共属性

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

另请参阅 where() 以了解指定此值的有效语法。

public string|array|yii\db\ExpressionInterface|null $where = null

方法详情

隐藏继承的方法

addOrderBy() 公共方法

向查询中添加额外的 ORDER BY 列。

另请参阅 orderBy()。

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

要按其排序的列（和方向）。列可以以字符串（例如“id ASC, name DESC”）或数组（例如['id' => SORT_ASC, 'name' => SORT_DESC]）的形式指定。

该方法会自动引用列名，除非列包含一些括号（这意味着列包含数据库表达式）。

请注意，如果您的 order-by 是包含逗号的表达式，则应始终使用数组来表示 order-by 信息。否则，该方法将无法正确确定 order-by 列。

从 2.0.7 版本开始，可以传递 yii\db\ExpressionInterface 对象以明确地以纯 SQL 指定 ORDER BY 部分。
返回值 $this

查询对象本身

 

                public function addOrderBy($columns)
{
    $columns = $this->normalizeOrderBy($columns);
    if ($this->orderBy === null) {
        $this->orderBy = $columns;
    } else {
        $this->orderBy = array_merge($this->orderBy, $columns);
    }
    return $this;
}
andFilterWhere() 公共方法

向现有的 WHERE 条件添加一个额外的条件，但忽略 空操作数。

新的条件和现有的条件将使用“AND”运算符连接。

此方法类似于 andWhere()。主要区别在于此方法将删除 空查询操作数。因此，此方法最适合根据用户输入的筛选值构建查询条件。

另请参阅

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

新的 WHERE 条件。请参阅 where() 以了解如何指定此参数。
返回值 $this

查询对象本身

 

                public function andFilterWhere(array $condition)
{
    $condition = $this->filterCondition($condition);
    if ($condition !== []) {
        $this->andWhere($condition);
    }
    return $this;
}
andWhere() 公共方法

向现有的 WHERE 条件添加一个额外的条件。

新的条件和现有的条件将使用“AND”运算符连接。

另请参阅

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

新的 WHERE 条件。请参阅 where() 以了解如何指定此参数。
返回值 $this

查询对象本身

 

                public function andWhere($condition)
{
    if ($this->where === null) {
        $this->where = $condition;
    } else {
        $this->where = ['and', $this->where, $condition];
    }
    return $this;
}
emulateExecution() 公共方法 (自 2.0.11 版本起可用)

设置是否模拟查询执行，防止与数据存储交互。

启用此模式后，返回查询结果的方法（如 yii\db\QueryInterface::one()、yii\db\QueryInterface::all()、yii\db\QueryInterface::exists() 等）将返回空值或 false 值。如果您程序逻辑指示查询不应返回任何结果，例如您设置了错误的 where 条件（如 0=1），则应使用此方法。

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

是否阻止查询执行。
返回值 $this

查询对象本身。

 

                public function emulateExecution($value = true)
{
    $this->emulateExecution = $value;
    return $this;
}
filterCondition() 受保护方法

从给定的查询条件中删除 空操作数。

protected array filterCondition ( $condition )
$condition array

原始条件
返回值 array

已删除 空操作数 的条件。
抛出 yii\base\NotSupportedException

如果条件运算符不受支持

 

                protected function filterCondition($condition)
{
    if (!is_array($condition)) {
        return $condition;
    }
    if (!isset($condition[0])) {
        // hash format: 'column1' => 'value1', 'column2' => 'value2', ...
        foreach ($condition as $name => $value) {
            if ($this->isEmpty($value)) {
                unset($condition[$name]);
            }
        }
        return $condition;
    }
    // operator format: operator, operand 1, operand 2, ...
    $operator = array_shift($condition);
    switch (strtoupper($operator)) {
        case 'NOT':
        case 'AND':
        case 'OR':
            foreach ($condition as $i => $operand) {
                $subCondition = $this->filterCondition($operand);
                if ($this->isEmpty($subCondition)) {
                    unset($condition[$i]);
                } else {
                    $condition[$i] = $subCondition;
                }
            }
            if (empty($condition)) {
                return [];
            }
            break;
        case 'BETWEEN':
        case 'NOT BETWEEN':
            if (array_key_exists(1, $condition) && array_key_exists(2, $condition)) {
                if ($this->isEmpty($condition[1]) || $this->isEmpty($condition[2])) {
                    return [];
                }
            }
            break;
        default:
            if (array_key_exists(1, $condition) && $this->isEmpty($condition[1])) {
                return [];
            }
    }
    array_unshift($condition, $operator);
    return $condition;
}
filterWhere() 公共方法

设置查询的 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]);

请注意，与 where() 不同，您不能将绑定参数传递给此方法。

另请参阅

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

应放在 WHERE 部分的条件。请参阅 where() 以了解如何指定此参数。
返回值 $this

查询对象本身

 

                public function filterWhere(array $condition)
{
    $condition = $this->filterCondition($condition);
    if ($condition !== []) {
        $this->where($condition);
    }
    return $this;
}
indexBy() 公共方法

设置 indexBy() 属性。

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

查询结果应按其索引的列的名称。这也可以是可调用对象（例如匿名函数），它根据给定的行数据返回索引值。可调用对象的签名应为

function ($row)
{
    // return the index value corresponding to $row
}
返回值 $this

查询对象本身

 

                public function indexBy($column)
{
    $this->indexBy = $column;
    return $this;
}
isEmpty() 受保护方法

返回一个值，指示给定值是否为“空”。

如果满足以下条件之一，则该值被视为“空”

  • 它是 null，
  • 空字符串 ('')，
  • 仅包含空格字符的字符串，
  • 或空数组。
protected boolean isEmpty ( $value )
$value mixed
返回值 boolean

如果值为 null

 

                protected function isEmpty($value)
{
    return $value === '' || $value === [] || $value === null || is_string($value) && trim($value) === '';
}
limit() 公共方法

设置查询的 LIMIT 部分。

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

限制数量。使用 null 或负值禁用限制。
返回值 $this

查询对象本身

 

                public function limit($limit)
{
    $this->limit = $limit;
    return $this;
}
normalizeOrderBy() 受保护方法

规范化 ORDER BY 数据的格式。

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

要标准化的列值。参见 orderBy() 和 addOrderBy()。

 

                protected function normalizeOrderBy($columns)
{
    if (empty($columns)) {
        return [];
    } elseif ($columns instanceof ExpressionInterface) {
        return [$columns];
    } elseif (is_array($columns)) {
        return $columns;
    }
    $columns = preg_split('/\s*,\s*/', trim($columns), -1, PREG_SPLIT_NO_EMPTY);
    $result = [];
    foreach ($columns as $column) {
        if (preg_match('/^(.*?)\s+(asc|desc)$/i', $column, $matches)) {
            $result[$matches[1]] = strcasecmp($matches[2], 'desc') ? SORT_ASC : SORT_DESC;
        } else {
            $result[$column] = SORT_ASC;
        }
    }
    return $result;
}
offset() 公共方法

设置查询的 OFFSET 部分。

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

偏移量。使用 null 或负值禁用偏移量。
返回值 $this

查询对象本身

 

                public function offset($offset)
{
    $this->offset = $offset;
    return $this;
}
orFilterWhere() 公共方法

向现有的 WHERE 条件添加一个额外的条件，但忽略 空操作数。

新的条件和现有的条件将使用 'OR' 运算符连接。

此方法类似于 orWhere()。主要区别在于此方法将删除 空的查询操作数。因此，此方法最适合根据用户输入的筛选值构建查询条件。

另请参阅

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

新的 WHERE 条件。请参阅 where() 以了解如何指定此参数。
返回值 $this

查询对象本身

 

                public function orFilterWhere(array $condition)
{
    $condition = $this->filterCondition($condition);
    if ($condition !== []) {
        $this->orWhere($condition);
    }
    return $this;
}
orWhere() 公共方法

向现有的 WHERE 条件添加一个额外的条件。

新的条件和现有的条件将使用 'OR' 运算符连接。

另请参阅

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

新的 WHERE 条件。请参阅 where() 以了解如何指定此参数。
返回值 $this

查询对象本身

 

                public function orWhere($condition)
{
    if ($this->where === null) {
        $this->where = $condition;
    } else {
        $this->where = ['or', $this->where, $condition];
    }
    return $this;
}
orderBy() 公共方法

设置查询的 ORDER BY 部分。

另请参阅 addOrderBy()。

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

要按其排序的列（和方向）。列可以以字符串（例如 "id ASC, name DESC"）或数组（例如 ['id' => SORT_ASC, 'name' => SORT_DESC]）的形式指定。

该方法会自动引用列名，除非列包含一些括号（这意味着列包含数据库表达式）。

请注意，如果您的 order-by 是包含逗号的表达式，则应始终使用数组来表示 order-by 信息。否则，该方法将无法正确确定 order-by 列。

从 2.0.7 版本开始，可以传递 yii\db\ExpressionInterface 对象以明确地以纯 SQL 指定 ORDER BY 部分。
返回值 $this

查询对象本身

 

                public function orderBy($columns)
{
    $this->orderBy = $this->normalizeOrderBy($columns);
    return $this;
}
where() 公共方法

设置查询的 WHERE 部分。

有关详细文档，请参阅 yii\db\QueryInterface::where()。

另请参阅

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

应放在 WHERE 部分的条件。
返回值 $this

查询对象本身

 

                public function where($condition)
{
    $this->where = $condition;
    return $this;
}