4 个关注者

类 yii\db\ActiveQuery

继承yii\db\ActiveQuery » yii\db\Query » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable, yii\db\ActiveQueryInterface, yii\db\ExpressionInterface, yii\db\QueryInterface
使用 Traityii\db\ActiveQueryTrait, yii\db\ActiveRelationTrait, yii\db\QueryTrait
可用版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/db/ActiveQuery.php

ActiveQuery 表示与 Active Record 类关联的数据库查询。

ActiveQuery 可以是普通查询,也可以用于关系上下文。

ActiveQuery 实例通常由 yii\db\ActiveRecord::find()yii\db\ActiveRecord::findBySql() 创建。关系查询由 yii\db\ActiveRecord::hasOne()yii\db\ActiveRecord::hasMany() 创建。

普通查询

ActiveQuery 主要提供以下方法来检索查询结果

  • one(): 返回一个包含第一行数据的单个记录。
  • all(): 返回基于查询结果的所有记录。
  • count(): 返回记录数量。
  • sum(): 返回指定列的总和。
  • average(): 返回指定列的平均值。
  • min(): 返回指定列的最小值。
  • max(): 返回指定列的最大值。
  • scalar(): 返回查询结果第一行第一列的值。
  • column(): 返回查询结果第一列的值。
  • exists(): 返回一个值,指示查询结果是否有数据。

因为 ActiveQuery 继承自 yii\db\Query,所以可以使用查询方法,例如 where()orderBy() 来自定义查询选项。

ActiveQuery 还提供以下其他查询选项

  • with(): 此查询应执行的关系列表。
  • joinWith(): 重用关系查询定义,将联接添加到查询。
  • indexBy(): 应按查询结果索引的列的名称。
  • asArray(): 是否将每条记录作为数组返回。

这些选项可以使用相同名称的方法进行配置。例如

$customers = Customer::find()->with('orders')->asArray()->all();

关系查询

在关系上下文中,ActiveQuery 表示两个 Active Record 类之间的关系。

关系 ActiveQuery 实例通常通过调用 yii\db\ActiveRecord::hasOne()yii\db\ActiveRecord::hasMany() 创建。Active Record 类通过定义调用上述方法之一并返回创建的 ActiveQuery 对象的 getter 方法来声明关系。

关系由 $link 指定,它表示不同表列之间的关联;关系的多重性由 $multiple 指示。

如果关系涉及联接表,则可以通过 via()viaTable() 方法指定。这些方法只能在关系上下文中调用。同样适用于 inverseOf(),它将关系标记为另一个关系的逆关系,以及 onCondition(),它添加一个要添加到关系查询联接条件的条件。

公共属性

隐藏继承的属性

属性 类型 描述 定义者
$asArray boolean 是否将每条记录作为数组返回。 yii\db\ActiveQueryTrait
$behaviors yii\base\Behavior[] 附加到此组件的行为列表。 yii\base\Component
$distinct boolean 是否仅选择不同的数据行。 yii\db\Query
$emulateExecution boolean 是否模拟实际查询执行,返回空或假结果。 yii\db\QueryTrait
$from array|null 要从中选择的表。 yii\db\Query
$groupBy array|null 如何对查询结果进行分组。 yii\db\Query
$having string|array|yii\db\ExpressionInterface|null 要在 GROUP BY 子句中应用的条件。 yii\db\Query
$indexBy string|callable|null 应按其索引查询结果的列的名称。 yii\db\QueryTrait
$inverseOf string 此关系的逆关系的名称。 yii\db\ActiveRelationTrait
$join array|null 如何与其他表联接。 yii\db\Query
$joinWith array|null 此查询应与之联接的关系列表 yii\db\ActiveQuery
$limit integer|yii\db\ExpressionInterface|null 要返回的记录的最大数量。 yii\db\QueryTrait
$modelClass string ActiveRecord 类的名称。 yii\db\ActiveQueryTrait
$multiple boolean 此查询是否表示与多个记录的关系。 yii\db\ActiveRelationTrait
$offset integer|yii\db\ExpressionInterface|null 从何处返回记录的零基偏移量。 yii\db\QueryTrait
$on string|array|null 当此查询用于关系上下文中时要使用的联接条件。 yii\db\ActiveQuery
$orderBy array|null 如何对查询结果进行排序。 yii\db\QueryTrait
$params array|null 按参数占位符索引的查询参数值列表。 yii\db\Query
$primaryModel yii\db\ActiveRecord 关系查询的主模型。 yii\db\ActiveRelationTrait
$queryCacheDependency yii\caching\Dependency|null 要与此查询的缓存查询结果关联的依赖项 yii\db\Query
$queryCacheDuration integer|boolean|null 查询结果可以在缓存中保持有效的默认秒数。 yii\db\Query
$select array|null 正在选择的列。 yii\db\Query
$selectOption string|null 应附加到“SELECT”关键字的附加选项。 yii\db\Query
$sql string|null 用于检索 AR 记录的要执行的 SQL 语句。 yii\db\ActiveQuery
$tablesUsedInFrom string[] 按别名索引的表名。 yii\db\Query
$union array|null 用于在 SQL 语句中构造 UNION 子句。 yii\db\Query
$via array|object 与联接表关联的查询。 yii\db\ActiveRelationTrait
$where string|array|yii\db\ExpressionInterface|null 查询条件。 yii\db\QueryTrait
$with array 此查询应与之执行的关系列表 yii\db\ActiveQueryTrait
$withQueries array|null 用于在 SQL 查询中构造 WITH 部分。 yii\db\Query

公共方法

隐藏继承的方法

方法 描述 定义者
__call() 调用不是类方法的命名方法。 yii\base\Component
__clone() 克隆内部对象。 yii\db\ActiveRelationTrait
__construct() 构造函数。 yii\db\ActiveQuery
__get() 返回组件属性的值。 yii\base\Component
__isset() 检查属性是否已设置,即定义且不为空。 yii\base\Component
__set() 设置组件属性的值。 yii\base\Component
__toString() 返回查询的 SQL 表示形式 yii\db\Query
__unset() 将组件属性设置为 null。 yii\base\Component
addGroupBy() 向现有的 group-by 列添加额外的 group-by 列。 yii\db\Query
addOrderBy() 向查询添加额外的 ORDER BY 列。 yii\db\QueryTrait
addParams() 添加要绑定到查询的额外参数。 yii\db\Query
addSelect() 向查询的 SELECT 部分添加更多列。 yii\db\Query
alias() 为在 $modelClass 中定义的表定义别名。 yii\db\ActiveQuery
all() 执行查询并以数组形式返回所有结果。 yii\db\ActiveQuery
andFilterCompare() 为特定列添加过滤条件,并允许用户选择过滤运算符。 yii\db\Query
andFilterHaving() 向现有的 HAVING 条件添加一个额外的 HAVING 条件,但忽略 空操作数 yii\db\Query
andFilterWhere() 向现有的 WHERE 条件添加一个额外的 WHERE 条件,但忽略 空操作数 yii\db\QueryTrait
andHaving() 向现有的 HAVING 条件添加一个额外的 HAVING 条件。 yii\db\Query
andOnCondition() 向现有的 ON 条件添加一个额外的 ON 条件。 yii\db\ActiveQuery
andWhere() 向现有的 WHERE 条件添加一个额外的 WHERE 条件。 yii\db\QueryTrait
asArray() 设置 asArray() 属性。 yii\db\ActiveQueryTrait
attachBehavior() 将行为附加到此组件。 yii\base\Component
attachBehaviors() 将行为列表附加到组件。 yii\base\Component
average() 返回指定列值的平均值。 yii\db\Query
batch() 开始批量查询。 yii\db\Query
behaviors() 返回此组件应表现为的行为列表。 yii\base\Component
cache() 为此查询启用查询缓存。 yii\db\Query
canGetProperty() 返回一个值,指示是否可以读取属性。 yii\base\Component
canSetProperty() 返回一个值,指示是否可以设置属性。 yii\base\Component
className() 返回此类的完全限定名称。 yii\base\BaseObject
column() 执行查询并返回结果的第一列。 yii\db\Query
count() 返回记录数量。 yii\db\Query
create() 创建一个新的 Query 对象,并从现有对象中复制其属性值。 yii\db\Query
createCommand() 创建一个可以用于执行此查询的 DB 命令。 yii\db\ActiveQuery
detachBehavior() 从组件分离行为。 yii\base\Component
detachBehaviors() 从组件分离所有行为。 yii\base\Component
distinct() 设置指示是否选择 DISTINCT 的值。 yii\db\Query
each() 开始批量查询并逐行检索数据。 yii\db\Query
emulateExecution() 设置是否模拟查询执行,防止与数据存储交互。 yii\db\QueryTrait
ensureBehaviors() 确保在 behaviors() 中声明的行为附加到此组件。 yii\base\Component
exists() 返回一个值,指示查询结果是否包含任何数据行。 yii\db\Query
filterHaving() 设置查询的 HAVING 部分,但忽略 空操作数 yii\db\Query
filterWhere() 设置查询的 WHERE 部分,但忽略 空操作数 yii\db\QueryTrait
findFor() 查找指定主记录的相关记录。 yii\db\ActiveRelationTrait
findWith() 查找与一个或多个关系相对应的记录,并将它们填充到主模型中。 yii\db\ActiveQueryTrait
from() 设置查询的 FROM 部分。 yii\db\Query
getBehavior() 返回命名的行为对象。 yii\base\Component
getBehaviors() 返回附加到此组件的所有行为。 yii\base\Component
getTablesUsedInFrom() 返回 from() 中使用的表名,按别名索引。 yii\db\ActiveQuery
groupBy() 设置查询的 GROUP BY 部分。 yii\db\Query
hasEventHandlers() 返回一个值,指示是否有任何处理程序附加到命名的事件。 yii\base\Component
hasMethod() 返回一个值,指示是否定义了方法。 yii\base\Component
hasProperty() 返回一个值,指示是否为此组件定义了属性。 yii\base\Component
having() 设置查询的 HAVING 部分。 yii\db\Query
indexBy() 设置 indexBy() 属性。 yii\db\QueryTrait
init() 初始化对象。 yii\db\ActiveQuery
innerJoin() 将 INNER JOIN 部分追加到查询。 yii\db\Query
innerJoinWith() 与指定的关系进行内部联接。 yii\db\ActiveQuery
inverseOf() 设置与该关系相反的关系的名称。 yii\db\ActiveRelationTrait
join() 将 JOIN 部分追加到查询。 yii\db\Query
joinWith() 与指定的关系进行联接。 yii\db\ActiveQuery
leftJoin() 将 LEFT OUTER JOIN 部分追加到查询。 yii\db\Query
limit() 设置查询的 LIMIT 部分。 yii\db\QueryTrait
max() 返回指定列值的最大值。 yii\db\Query
min() 返回指定列值的最小值。 yii\db\Query
noCache() 为此查询禁用查询缓存。 yii\db\Query
off() 从此组件分离现有的事件处理程序。 yii\base\Component
offset() 设置查询的 OFFSET 部分。 yii\db\QueryTrait
on() 将事件处理程序附加到事件。 yii\base\Component
onCondition() 设置关系查询的 ON 条件。 yii\db\ActiveQuery
one() 执行查询并返回一行结果。 yii\db\ActiveQuery
orFilterHaving() 向现有的 HAVING 条件添加一个额外的 HAVING 条件,但忽略 空操作数 yii\db\Query
orFilterWhere() 向现有的 WHERE 条件添加一个额外的 WHERE 条件,但忽略 空操作数 yii\db\QueryTrait
orHaving() 向现有的 HAVING 条件添加一个额外的 HAVING 条件。 yii\db\Query
orOnCondition() 向现有的 ON 条件添加一个额外的 ON 条件。 yii\db\ActiveQuery
orWhere() 向现有的 WHERE 条件添加一个额外的 WHERE 条件。 yii\db\QueryTrait
orderBy() 设置查询的 ORDER BY 部分。 yii\db\QueryTrait
params() 设置要绑定到查询的参数。 yii\db\Query
populate() 将原始查询结果转换为此查询指定的格式。 yii\db\ActiveQuery
populateRelation() 查找相关记录并将它们填充到主模型中。 yii\db\ActiveRelationTrait
prepare() 准备构建 SQL。 yii\db\ActiveQuery
rightJoin() 将 RIGHT OUTER JOIN 部分追加到查询。 yii\db\Query
scalar() 将查询结果作为标量值返回。 yii\db\Query
select() 设置查询的 SELECT 部分。 yii\db\Query
sum() 返回指定列值的总和。 yii\db\Query
trigger() 触发事件。 yii\base\Component
union() 使用 UNION 运算符追加 SQL 语句。 yii\db\Query
via() 指定与联接表关联的关系。 yii\db\ActiveRelationTrait
viaTable() 为关系查询指定联接表。 yii\db\ActiveQuery
where() 设置查询的 WHERE 部分。 yii\db\QueryTrait
with() 指定应执行此查询的关系。 yii\db\ActiveQueryTrait
withQuery() 使用 WITH 语法追加 SQL 语句。 yii\db\Query

受保护方法

隐藏继承的方法

方法 描述 定义者
cleanUpTableNames() 清理表名和别名 别名和名称都用 {{ 和 }} 包围。 yii\db\Query
createModels() 将找到的行转换为模型实例。 yii\db\ActiveQueryTrait
filterCondition() 从给定的查询条件中删除 空操作数 yii\db\QueryTrait
getPrimaryTableName() yii\db\ActiveQuery
getTableNameAndAlias() 返回 $modelClass 的表名和表别名。 yii\db\ActiveQuery
getUnaliasedColumnsFromSelect() yii\db\Query
getUniqueColumns() 返回唯一的列名,排除重复项。 yii\db\Query
isEmpty() 返回一个值,指示给定值是否为“空”。 yii\db\QueryTrait
normalizeOrderBy() 规范化 ORDER BY 数据的格式。 yii\db\QueryTrait
normalizeSelect() 规范化传递给 select()addSelect() 的 SELECT 列。 yii\db\Query
queryScalar() 通过首先设置 select() 来查询标量值。 yii\db\ActiveQuery
setCommandCache() 设置 $command 缓存,如果此查询启用了缓存。 yii\db\Query

事件

隐藏继承的事件

事件 类型 描述 定义者
EVENT_INIT yii\db\Event 通过 init() 初始化查询时触发的事件。 yii\db\ActiveQuery

属性详细信息

隐藏继承的属性

$joinWith 公共属性

此查询应与之联接的关系列表

public array|null $joinWith null
$on 公共属性

当此查询在关系上下文中使用时要使用的联接条件。当调用 yii\db\ActiveQuery::joinWith() 时,该条件将在 ON 部分中使用。否则,该条件将在查询的 WHERE 部分中使用。有关如何指定此参数的详细信息,请参考 yii\db\Query::where()

另请参阅 onCondition()

public string|array|null $on null
$sql 公共属性

用于检索 AR 记录要执行的 SQL 语句。由 yii\db\ActiveRecord::findBySql() 设置。

public string|null $sql null

方法详细信息

隐藏继承的方法

__call() 公共方法

定义于: yii\base\Component::__call()

调用不是类方法的命名方法。

此方法将检查是否有任何附加的行为具有命名方法,如果可用,则执行该方法。

不要直接调用此方法,因为它是一个 PHP 魔术方法,当调用未知方法时会隐式调用。

public mixed __call ( $name, $params )
$name string

方法名称

$params array

方法参数

返回值 mixed

方法返回值

抛出 yii\base\UnknownMethodException

调用未知方法时

                public function __call($name, $params)
{
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $object) {
        if ($object->hasMethod($name)) {
            return call_user_func_array([$object, $name], $params);
        }
    }
    throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
}

            
__clone() 公共方法

定义于: yii\db\ActiveRelationTrait::__clone()

克隆内部对象。

public void __clone ( )

                public function __clone()
{
    parent::__clone();
    // make a clone of "via" object so that the same query object can be reused multiple times
    if (is_object($this->via)) {
        $this->via = clone $this->via;
    } elseif (is_array($this->via)) {
        $this->via = [$this->via[0], clone $this->via[1], $this->via[2]];
    }
}

            
__construct() 公共方法

构造函数。

public void __construct ( $modelClass, $config = [] )
$modelClass string

与该查询关联的模型类

$config array

要应用于新创建的查询对象的配置

                public function __construct($modelClass, $config = [])
{
    $this->modelClass = $modelClass;
    parent::__construct($config);
}

            
__get() 公共方法

定义于: yii\base\Component::__get()

返回组件属性的值。

此方法将按照以下顺序检查并相应地执行

  • 由 getter 定义的属性:返回 getter 结果
  • 行为的属性:返回行为属性值

不要直接调用此方法,因为它是一个 PHP 魔术方法,当执行 $value = $component->property; 时会隐式调用。

另见 __set().

public mixed __get ( $name )
$name string

属性名称

返回值 mixed

属性值或行为属性的值

抛出 yii\base\UnknownPropertyException

如果未定义属性

抛出 yii\base\InvalidCallException

如果属性是只写的。

                public function __get($name)
{
    $getter = 'get' . $name;
    if (method_exists($this, $getter)) {
        // read property, e.g. getName()
        return $this->$getter();
    }
    // behavior property
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $behavior) {
        if ($behavior->canGetProperty($name)) {
            return $behavior->$name;
        }
    }
    if (method_exists($this, 'set' . $name)) {
        throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
    }
    throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
}

            
__isset() 公共方法

定义于: yii\base\Component::__isset()

检查属性是否已设置,即定义且不为空。

此方法将按照以下顺序检查并相应地执行

  • 由 setter 定义的属性:返回属性是否已设置
  • 行为的属性:返回属性是否已设置
  • 对于不存在的属性返回 false

不要直接调用此方法,因为它是一个 PHP 魔术方法,当执行 isset($component->property) 时会隐式调用。

另见 https://php.ac.cn/manual/en/function.isset.php.

public boolean __isset ( $name )
$name string

属性名称或事件名称

返回值 boolean

命名属性是否已设置

                public function __isset($name)
{
    $getter = 'get' . $name;
    if (method_exists($this, $getter)) {
        return $this->$getter() !== null;
    }
    // behavior property
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $behavior) {
        if ($behavior->canGetProperty($name)) {
            return $behavior->$name !== null;
        }
    }
    return false;
}

            
__set() 公共方法

定义于: yii\base\Component::__set()

设置组件属性的值。

此方法将按照以下顺序检查并相应地执行

  • 由 setter 定义的属性:设置属性值
  • 以 "on xyz" 格式的事件:将处理程序附加到事件 "xyz"
  • 以 "as xyz" 格式的行为:附加名为 "xyz" 的行为
  • 行为的属性:设置行为属性值

不要直接调用此方法,因为它是一个 PHP 魔术方法,当执行 $component->property = $value; 时会隐式调用。

另见 __get().

public void __set ( $name, $value )
$name string

属性名称或事件名称

$value mixed

属性值

抛出 yii\base\UnknownPropertyException

如果未定义属性

抛出 yii\base\InvalidCallException

如果属性是只读的。

                public function __set($name, $value)
{
    $setter = 'set' . $name;
    if (method_exists($this, $setter)) {
        // set property
        $this->$setter($value);
        return;
    } elseif (strncmp($name, 'on ', 3) === 0) {
        // on event: attach event handler
        $this->on(trim(substr($name, 3)), $value);
        return;
    } elseif (strncmp($name, 'as ', 3) === 0) {
        // as behavior: attach behavior
        $name = trim(substr($name, 3));
        $this->attachBehavior($name, $value instanceof Behavior ? $value : Yii::createObject($value));
        return;
    }
    // behavior property
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $behavior) {
        if ($behavior->canSetProperty($name)) {
            $behavior->$name = $value;
            return;
        }
    }
    if (method_exists($this, 'get' . $name)) {
        throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
    }
    throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
}

            
__toString() 公共方法

定义于: yii\db\Query::__toString()

返回查询的 SQL 表示形式

public string __toString ( )

                public function __toString()
{
    return serialize($this);
}

            
__unset() 公共方法

定义于: yii\base\Component::__unset()

将组件属性设置为 null。

此方法将按照以下顺序检查并相应地执行

  • 由 setter 定义的属性:将属性值设置为 null
  • 行为的属性:将属性值设置为 null

不要直接调用此方法,因为它是一个 PHP 魔术方法,当执行 unset($component->property) 时会隐式调用。

另见 https://php.ac.cn/manual/en/function.unset.php.

public void __unset ( $name )
$name string

属性名称

抛出 yii\base\InvalidCallException

如果属性是只读的。

                public function __unset($name)
{
    $setter = 'set' . $name;
    if (method_exists($this, $setter)) {
        $this->$setter(null);
        return;
    }
    // behavior property
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $behavior) {
        if ($behavior->canSetProperty($name)) {
            $behavior->$name = null;
            return;
        }
    }
    throw new InvalidCallException('Unsetting an unknown or read-only property: ' . get_class($this) . '::' . $name);
}

            
addGroupBy() 公共方法

定义于: yii\db\Query::addGroupBy()

向现有的 group-by 列添加额外的 group-by 列。

另见 groupBy().

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

要分组的其他列。列可以以字符串(例如 "id, name")或数组(例如 ['id', 'name'])形式指定。该方法将自动引用列名,除非列包含一些括号(表示列包含 DB 表达式)。

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

从版本 2.0.7 开始,可以传递 yii\db\Expression 对象以显式地用纯 SQL 指定 GROUP BY 部分。从版本 2.0.14 开始,也可以传递 yii\db\ExpressionInterface 对象。

返回值 $this

查询对象本身

                public function addGroupBy($columns)
{
    if ($columns instanceof ExpressionInterface) {
        $columns = [$columns];
    } elseif (!is_array($columns)) {
        $columns = preg_split('/\s*,\s*/', trim($columns), -1, PREG_SPLIT_NO_EMPTY);
    }
    if ($this->groupBy === null) {
        $this->groupBy = $columns;
    } else {
        $this->groupBy = array_merge($this->groupBy, $columns);
    }
    return $this;
}

            
addOrderBy() 公共方法

定义于: yii\db\QueryTrait::addOrderBy()

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

另见 orderBy().

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

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

除非列包含一些括号(这意味着列包含 DB 表达式),否则该方法将自动引用列名。

请注意,如果您的排序条件是一个包含逗号的表达式,则应始终使用数组来表示排序条件信息。否则,该方法将无法正确确定排序列。

从 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;
}

            
addParams() 公共方法

定义于: yii\db\Query::addParams()

添加要绑定到查询的额外参数。

另请参见 params().

public $this addParams ( $params )
$params array

按参数占位符索引的查询参数值列表。例如,[':name' => 'Dan', ':age' => 31]

返回值 $this

查询对象本身

                public function addParams($params)
{
    if (!empty($params)) {
        if (empty($this->params)) {
            $this->params = $params;
        } else {
            foreach ($params as $name => $value) {
                if (is_int($name)) {
                    $this->params[] = $value;
                } else {
                    $this->params[$name] = $value;
                }
            }
        }
    }
    return $this;
}

            
addSelect() 公共方法

定义于: yii\db\Query::addSelect()

向查询的 SELECT 部分添加更多列。

请注意,如果之前没有指定select(),那么如果您还想选择所有剩余的列,则应明确地包含*

$query->addSelect(["*", "CONCAT(first_name, ' ', last_name) AS full_name"])->one();

另请参见 select().

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

要添加到选择的列。有关此参数格式的更多详细信息,请参见select()

返回值 $this

查询对象本身

                public function addSelect($columns)
{
    if ($this->select === null) {
        return $this->select($columns);
    }
    if (!is_array($this->select)) {
        $this->select = $this->normalizeSelect($this->select);
    }
    $this->select = array_merge($this->select, $this->normalizeSelect($columns));
    return $this;
}

            
alias() 公共方法 (从版本 2.0.7 开始可用)

为在 $modelClass 中定义的表定义别名。

此方法将调整from(),以便覆盖已定义的别名。如果未定义,则from() 将使用给定的别名进行填充。

public $this alias ( $alias )
$alias string

表别名。

返回值 $this

查询对象本身

                public function alias($alias)
{
    if (empty($this->from) || count($this->from) < 2) {
        list($tableName) = $this->getTableNameAndAlias();
        $this->from = [$alias => $tableName];
    } else {
        $tableName = $this->getPrimaryTableName();
        foreach ($this->from as $key => $table) {
            if ($table === $tableName) {
                unset($this->from[$key]);
                $this->from[$alias] = $tableName;
            }
        }
    }
    return $this;
}

            
all() 公共方法

执行查询并以数组形式返回所有结果。

public array|yii\db\ActiveRecord[] all ( $db null )
$db yii\db\Connection|null

用于创建 DB 命令的 DB 连接。如果为 null,将使用$modelClass 返回的 DB 连接。

返回值 array|yii\db\ActiveRecord[]

查询结果。如果查询结果为空,则将返回空数组。

                public function all($db = null)
{
    return parent::all($db);
}

            
andFilterCompare() 公共方法 (从版本 2.0.8 开始可用)

定义于: yii\db\Query::andFilterCompare()

为特定列添加过滤条件,并允许用户选择过滤运算符。

它为给定字段添加一个额外的 WHERE 条件,并根据给定值的开头几个字符确定比较运算符。条件以与andFilterWhere() 中相同的方式添加,因此空值 将被忽略。新条件和现有条件将使用AND 运算符连接。

比较运算符是根据给定值中的开头几个字符智能地确定的。特别是,它会识别以下运算符,如果它们作为给定值的开头字符出现

  • <:列必须小于给定值。
  • >:列必须大于给定值。
  • <=:列必须小于或等于给定值。
  • >=:列必须大于或等于给定值。
  • <>:列不能与给定值相同。
  • =:列必须等于给定值。
  • 如果未检测到上述任何运算符,则将使用$defaultOperator
public $this andFilterCompare ( $name, $value, $defaultOperator '=' )
$name string

列名。

$value string

列值,可选地以比较运算符为前缀。

$defaultOperator string

$value 中未给出运算符时要使用的运算符。默认为=,执行精确匹配。

返回值 $this

查询对象本身

                public function andFilterCompare($name, $value, $defaultOperator = '=')
{
    if (preg_match('/^(<>|>=|>|<=|<|=)/', (string)$value, $matches)) {
        $operator = $matches[1];
        $value = substr($value, strlen($operator));
    } else {
        $operator = $defaultOperator;
    }
    return $this->andFilterWhere([$operator, $name, $value]);
}

            
andFilterHaving() 公共方法 (从版本 2.0.11 开始可用)

定义于: yii\db\Query::andFilterHaving()

向现有的 HAVING 条件添加一个额外的 HAVING 条件,但忽略 空操作数

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

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

另请参见

public $this andFilterHaving ( array $condition )
$condition array

新的 HAVING 条件。有关如何指定此参数的信息,请参阅having()

返回值 $this

查询对象本身

                public function andFilterHaving(array $condition)
{
    $condition = $this->filterCondition($condition);
    if ($condition !== []) {
        $this->andHaving($condition);
    }
    return $this;
}

            
andFilterWhere() 公共方法

定义于: yii\db\QueryTrait::andFilterWhere()

向现有的 WHERE 条件添加一个额外的 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;
}

            
andHaving() 公共方法

定义于: yii\db\Query::andHaving()

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

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

另请参见

public $this andHaving ( $condition, $params = [] )
$condition string|array|yii\db\ExpressionInterface

新的 HAVING 条件。有关如何指定此参数的信息,请参阅where()

$params array

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

返回值 $this

查询对象本身

                public function andHaving($condition, $params = [])
{
    if ($this->having === null) {
        $this->having = $condition;
    } else {
        $this->having = ['and', $this->having, $condition];
    }
    $this->addParams($params);
    return $this;
}

            
andOnCondition() 公共方法

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

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

另请参见

public $this andOnCondition ( $condition, $params = [] )
$condition string|array

新的 ON 条件。有关如何指定此参数的信息,请参阅where()

$params array

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

返回值 $this

查询对象本身

                public function andOnCondition($condition, $params = [])
{
    if ($this->on === null) {
        $this->on = $condition;
    } else {
        $this->on = ['and', $this->on, $condition];
    }
    $this->addParams($params);
    return $this;
}

            
andWhere() 公共方法

定义于: yii\db\QueryTrait::andWhere()

向现有的 WHERE 条件添加一个额外的 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;
}

            
asArray() 公共方法

定义于: yii\db\ActiveQueryTrait::asArray()

设置 asArray() 属性。

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

是否以数组形式而不是活动记录的形式返回查询结果。

返回值 $this

查询对象本身

                public function asArray($value = true)
{
    $this->asArray = $value;
    return $this;
}

            
attachBehavior() 公共方法

定义于: yii\base\Component::attachBehavior()

将行为附加到此组件。

此方法将根据给定的配置创建行为对象。之后,行为对象将通过调用 yii\base\Behavior::attach() 方法附加到此组件。

另请参阅 detachBehavior().

public yii\base\Behavior attachBehavior ( $name, $behavior )
$name string

行为的名称。

$behavior string|array|yii\base\Behavior

行为配置。可以是以下之一

返回值 yii\base\Behavior

行为对象

                public function attachBehavior($name, $behavior)
{
    $this->ensureBehaviors();
    return $this->attachBehaviorInternal($name, $behavior);
}

            
attachBehaviors() 公共方法

定义于: yii\base\Component::attachBehaviors()

将行为列表附加到组件。

每个行为都由其名称索引,并且应为 yii\base\Behavior 对象、指定行为类的字符串或用于创建行为的配置数组。

另请参阅 attachBehavior().

public void attachBehaviors ( $behaviors )
$behaviors array

要附加到组件的行为列表

                public function attachBehaviors($behaviors)
{
    $this->ensureBehaviors();
    foreach ($behaviors as $name => $behavior) {
        $this->attachBehaviorInternal($name, $behavior);
    }
}

            
average() 公共方法

定义于: yii\db\Query::average()

返回指定列值的平均值。

public mixed average ( $q, $db null )
$q string

列名或表达式。确保您在表达式中正确 引用 列名。

$db yii\db\Connection|null

用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 db 应用程序组件。

返回值 mixed

指定列值的平均值。

                public function average($q, $db = null)
{
    if ($this->emulateExecution) {
        return 0;
    }
    return $this->queryScalar("AVG($q)", $db);
}

            
batch() 公共方法

定义于: yii\db\Query::batch()

开始批量查询。

批量查询支持分批获取数据,这可以将内存使用量控制在一定范围内。此方法将返回一个 yii\db\BatchQueryResult 对象,该对象实现了 Iterator 接口,并且可以遍历以分批检索数据。

例如:

$query = (new Query)->from('user');
foreach ($query->batch() as $rows) {
    // $rows is an array of 100 or fewer rows from user table
}
public yii\db\BatchQueryResult batch ( $batchSize 100, $db null )
$batchSize integer

每次批次中要获取的记录数。

$db yii\db\Connection|null

数据库连接。如果未设置,将使用“db”应用程序组件。

返回值 yii\db\BatchQueryResult

批量查询结果。它实现了 Iterator 接口,并且可以遍历以分批检索数据。

                public function batch($batchSize = 100, $db = null)
{
    return Yii::createObject([
        'class' => BatchQueryResult::className(),
        'query' => $this,
        'batchSize' => $batchSize,
        'db' => $db,
        'each' => false,
    ]);
}

            
behaviors() 公共方法

定义于: yii\base\Component::behaviors()

返回此组件应表现为的行为列表。

子类可以重写此方法来指定它们希望表现的行为。

此方法的返回值应为行为对象或配置的数组,这些对象或配置由行为名称索引。行为配置可以是指定行为类的字符串,也可以是以下结构的数组

'behaviorName' => [
    'class' => 'BehaviorClass',
    'property1' => 'value1',
    'property2' => 'value2',
]

请注意,行为类必须扩展自 yii\base\Behavior。行为可以使用名称或匿名方式附加。当使用名称作为数组键时,使用此名称,行为稍后可以使用 getBehavior() 检索,或使用 detachBehavior() 分离。匿名行为不能检索或分离。

在此方法中声明的行为将自动附加到组件(按需)。

public array behaviors ( )
返回值 array

行为配置。

                public function behaviors()
{
    return [];
}

            
cache() 公共方法 (自版本 2.0.14 起可用)

定义于: yii\db\Query::cache()

为此查询启用查询缓存。

public $this cache ( $duration true, $dependency null )
$duration integer|true

查询结果可以在缓存中保持有效的秒数。使用 0 表示缓存的数据永不过期。使用负数表示不应使用查询缓存。使用布尔值 true 表示应使用 yii\db\Connection::$queryCacheDuration。默认为 true

$dependency yii\caching\Dependency|null

与缓存结果关联的缓存依赖项。

返回值 $this

查询对象本身

                public function cache($duration = true, $dependency = null)
{
    $this->queryCacheDuration = $duration;
    $this->queryCacheDependency = $dependency;
    return $this;
}

            
canGetProperty() 公共方法

定义于: yii\base\Component::canGetProperty()

返回一个值,指示是否可以读取属性。

如果可以读取属性,则

  • 该类具有与指定名称关联的 getter 方法(在这种情况下,属性名称不区分大小写);
  • 该类具有与指定名称相同的成员变量(当 $checkVars 为 true 时);
  • 附加的行为具有给定名称的可读属性(当 $checkBehaviors 为 true 时)。

另请参阅 canSetProperty().

public boolean canGetProperty ( $name, $checkVars true, $checkBehaviors true )
$name string

属性名称

$checkVars boolean

是否将成员变量视为属性

$checkBehaviors boolean

是否将行为的属性视为此组件的属性

返回值 boolean

该属性是否可读

                public function canGetProperty($name, $checkVars = true, $checkBehaviors = true)
{
    if (method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name)) {
        return true;
    } elseif ($checkBehaviors) {
        $this->ensureBehaviors();
        foreach ($this->_behaviors as $behavior) {
            if ($behavior->canGetProperty($name, $checkVars)) {
                return true;
            }
        }
    }
    return false;
}

            
canSetProperty() 公共方法

定义于: yii\base\Component::canSetProperty()

返回一个值,指示是否可以设置属性。

如果可以写入属性,则

  • 类具有与指定名称关联的 setter 方法(在这种情况下,属性名称不区分大小写);
  • 该类具有与指定名称相同的成员变量(当 $checkVars 为 true 时);
  • 附加的行为具有给定名称的可写属性(当 $checkBehaviors 为 true 时)。

另请参阅 canGetProperty().

public boolean canSetProperty ( $name, $checkVars true, $checkBehaviors true )
$name string

属性名称

$checkVars boolean

是否将成员变量视为属性

$checkBehaviors boolean

是否将行为的属性视为此组件的属性

返回值 boolean

该属性是否可写

                public function canSetProperty($name, $checkVars = true, $checkBehaviors = true)
{
    if (method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name)) {
        return true;
    } elseif ($checkBehaviors) {
        $this->ensureBehaviors();
        foreach ($this->_behaviors as $behavior) {
            if ($behavior->canSetProperty($name, $checkVars)) {
                return true;
            }
        }
    }
    return false;
}

            
className() 公共静态方法
自 2.0.14 版本起已弃用。在 PHP >=5.5 上,请改用 ::class

定义于: yii\base\BaseObject::className()

返回此类的完全限定名称。

public static string className ( )
返回值 string

此类的完全限定名称。

                public static function className()
{
    return get_called_class();
}

            
cleanUpTableNames() 受保护的方法 (自版本 2.0.14 起可用)

定义于: yii\db\Query::cleanUpTableNames()

清理表名和别名 别名和名称都用 {{ 和 }} 包围。

protected string[] cleanUpTableNames ( $tableNames )
$tableNames array

非空数组

返回值 string[]

以别名作为索引的表名

                protected function cleanUpTableNames($tableNames)
{
    $cleanedUpTableNames = [];
    foreach ($tableNames as $alias => $tableName) {
        if (is_string($tableName) && !is_string($alias)) {
            $pattern = <<<PATTERN
'"`\[]|{{)
'"`\]]|}})
?\)
\s+
(?:as)?
\s*
?:['"`\[]|{{)
.*?
(?:['"`\]]|}})
|
.*?

ERN;
            if (preg_match($pattern, $tableName, $matches)) {
                if (isset($matches[2])) {
                    list(, $tableName, $alias) = $matches;
                } else {
                    $tableName = $alias = $matches[1];
                }
            }
        }
        if ($tableName instanceof Expression) {
            if (!is_string($alias)) {
                throw new InvalidArgumentException('To use Expression in from() method, pass it in array format with alias.');
            }
            $cleanedUpTableNames[$this->ensureNameQuoted($alias)] = $tableName;
        } elseif ($tableName instanceof self) {
            $cleanedUpTableNames[$this->ensureNameQuoted($alias)] = $tableName;
        } else {
            $cleanedUpTableNames[$this->ensureNameQuoted($alias)] = $this->ensureNameQuoted($tableName);
        }
    }
    return $cleanedUpTableNames;
}

            
column() 公共方法

定义于: yii\db\Query::column()

执行查询并返回结果的第一列。

public array column ( $db null )
$db yii\db\Connection|null

用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 db 应用程序组件。

返回值 array

查询结果的第一列。如果查询结果为空,则返回空数组。

                public function column($db = null)
{
    if ($this->emulateExecution) {
        return [];
    }
    if ($this->indexBy === null) {
        return $this->createCommand($db)->queryColumn();
    }
    if (is_string($this->indexBy) && is_array($this->select) && count($this->select) === 1) {
        if (strpos($this->indexBy, '.') === false && count($tables = $this->getTablesUsedInFrom()) > 0) {
            $this->select[] = key($tables) . '.' . $this->indexBy;
        } else {
            $this->select[] = $this->indexBy;
        }
    }
    $rows = $this->createCommand($db)->queryAll();
    $results = [];
    $column = null;
    if (is_string($this->indexBy)) {
        if (($dotPos = strpos($this->indexBy, '.')) === false) {
            $column = $this->indexBy;
        } else {
            $column = substr($this->indexBy, $dotPos + 1);
        }
    }
    foreach ($rows as $row) {
        $value = reset($row);
        if ($this->indexBy instanceof \Closure) {
            $results[call_user_func($this->indexBy, $row)] = $value;
        } else {
            $results[$row[$column]] = $value;
        }
    }
    return $results;
}

            
count() 公共方法

定义于: yii\db\Query::count()

返回记录数量。

public integer|string|null count ( $q '*', $db null )
$q string

COUNT 表达式。默认值为 '*'. 确保您在表达式中正确 引用 列名。

$db yii\db\Connection|null

用于生成 SQL 语句的数据库连接。如果此参数未给出(或为 null),则将使用 db 应用程序组件。

返回值 integer|string|null

记录数量。结果可能是一个字符串,具体取决于底层数据库引擎,以支持高于 32 位 PHP 整数所能处理的整数。

                public function count($q = '*', $db = null)
{
    if ($this->emulateExecution) {
        return 0;
    }
    return $this->queryScalar("COUNT($q)", $db);
}

            
create() 公共静态方法

定义于: yii\db\Query::create()

创建一个新的 Query 对象,并从现有对象中复制其属性值。

正在复制的属性是查询构建器将使用的属性。

public static yii\db\Query create ( $from )
$from yii\db\Query

源查询对象

返回值 yii\db\Query

新的 Query 对象

                public static function create($from)
{
    return new self([
        'where' => $from->where,
        'limit' => $from->limit,
        'offset' => $from->offset,
        'orderBy' => $from->orderBy,
        'indexBy' => $from->indexBy,
        'select' => $from->select,
        'selectOption' => $from->selectOption,
        'distinct' => $from->distinct,
        'from' => $from->from,
        'groupBy' => $from->groupBy,
        'join' => $from->join,
        'having' => $from->having,
        'union' => $from->union,
        'params' => $from->params,
        'withQueries' => $from->withQueries,
    ]);
}

            
createCommand() 公共方法

创建一个可以用于执行此查询的 DB 命令。

public yii\db\Command createCommand ( $db null )
$db yii\db\Connection|null

用于创建 DB 命令的 DB 连接。如果为 null,则将使用 $modelClass 返回的 DB 连接。

返回值 yii\db\Command

创建的 DB 命令实例。

                public function createCommand($db = null)
{
    /* @var $modelClass ActiveRecord */
    $modelClass = $this->modelClass;
    if ($db === null) {
        $db = $modelClass::getDb();
    }
    if ($this->sql === null) {
        list($sql, $params) = $db->getQueryBuilder()->build($this);
    } else {
        $sql = $this->sql;
        $params = $this->params;
    }
    $command = $db->createCommand($sql, $params);
    $this->setCommandCache($command);
    return $command;
}

            
createModels() 受保护的方法 (自版本 2.0.11 起可用)

定义于: yii\db\ActiveQueryTrait::createModels()

将找到的行转换为模型实例。

protected array|yii\db\ActiveRecord[] createModels ( $rows )
$rows array

                protected function createModels($rows)
{
    if ($this->asArray) {
        return $rows;
    } else {
        $models = [];
        /* @var $class ActiveRecord */
        $class = $this->modelClass;
        foreach ($rows as $row) {
            $model = $class::instantiate($row);
            $modelClass = get_class($model);
            $modelClass::populateRecord($model, $row);
            $models[] = $model;
        }
        return $models;
    }
}

            
detachBehavior() 公共方法

定义于: yii\base\Component::detachBehavior()

从组件分离行为。

将调用行为的 yii\base\Behavior::detach() 方法。

public yii\base\Behavior|null detachBehavior ( $name )
$name string

行为的名称。

返回值 yii\base\Behavior|null

分离的行为。如果行为不存在,则为 Null。

                public function detachBehavior($name)
{
    $this->ensureBehaviors();
    if (isset($this->_behaviors[$name])) {
        $behavior = $this->_behaviors[$name];
        unset($this->_behaviors[$name]);
        $behavior->detach();
        return $behavior;
    }
    return null;
}

            
detachBehaviors() 公共方法

定义于: yii\base\Component::detachBehaviors()

从组件分离所有行为。

public void detachBehaviors ( )

                public function detachBehaviors()
{
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $name => $behavior) {
        $this->detachBehavior($name);
    }
}

            
distinct() 公共方法

定义于: yii\db\Query::distinct()

设置指示是否选择 DISTINCT 的值。

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

是否选择 DISTINCT 或不选择 DISTINCT。

返回值 $this

查询对象本身

                public function distinct($value = true)
{
    $this->distinct = $value;
    return $this;
}

            
each() public method

定义在: yii\db\Query::each()

开始批量查询并逐行检索数据。

此方法类似于 batch(),区别在于在结果的每次迭代中,只返回一行数据。例如,

$query = (new Query)->from('user');
foreach ($query->each() as $row) {
}
public yii\db\BatchQueryResult each ( $batchSize 100, $db null )
$batchSize integer

每次批次中要获取的记录数。

$db yii\db\Connection|null

数据库连接。如果未设置,将使用“db”应用程序组件。

返回值 yii\db\BatchQueryResult

批量查询结果。它实现了 Iterator 接口,并且可以遍历以分批检索数据。

                public function each($batchSize = 100, $db = null)
{
    return Yii::createObject([
        'class' => BatchQueryResult::className(),
        'query' => $this,
        'batchSize' => $batchSize,
        'db' => $db,
        'each' => true,
    ]);
}

            
emulateExecution() public method (available since version 2.0.11)

定义在: yii\db\QueryTrait::emulateExecution()

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

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

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

是否阻止查询执行。

返回值 $this

查询对象本身。

                public function emulateExecution($value = true)
{
    $this->emulateExecution = $value;
    return $this;
}

            
ensureBehaviors() public method

定义在: yii\base\Component::ensureBehaviors()

确保在 behaviors() 中声明的行为附加到此组件。

public void ensureBehaviors ( )

                public function ensureBehaviors()
{
    if ($this->_behaviors === null) {
        $this->_behaviors = [];
        foreach ($this->behaviors() as $name => $behavior) {
            $this->attachBehaviorInternal($name, $behavior);
        }
    }
}

            
exists() public method

定义在: yii\db\Query::exists()

返回一个值,指示查询结果是否包含任何数据行。

public boolean exists ( $db null )
$db yii\db\Connection|null

用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 db 应用程序组件。

返回值 boolean

查询结果是否包含任何数据行。

                public function exists($db = null)
{
    if ($this->emulateExecution) {
        return false;
    }
    $command = $this->createCommand($db);
    $params = $command->params;
    $command->setSql($command->db->getQueryBuilder()->selectExists($command->getSql()));
    $command->bindValues($params);
    return (bool) $command->queryScalar();
}

            
filterCondition() protected method

定义在: yii\db\QueryTrait::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;
}

            
filterHaving() public method (available since version 2.0.11)

定义在: yii\db\Query::filterHaving()

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

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

以下代码展示了此方法与 having() 之间的区别

// HAVING `age`=:age
$query->filterHaving(['name' => null, 'age' => 20]);
// HAVING `age`=:age
$query->having(['age' => 20]);
// HAVING `name` IS NULL AND `age`=:age
$query->having(['name' => null, 'age' => 20]);

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

另请参见

public $this filterHaving ( array $condition )
$condition array

应该放在 HAVING 部分的条件。有关如何指定此参数,请参阅 having()

返回值 $this

查询对象本身

                public function filterHaving(array $condition)
{
    $condition = $this->filterCondition($condition);
    if ($condition !== []) {
        $this->having($condition);
    }
    return $this;
}

            
filterWhere() public method

定义在: yii\db\QueryTrait::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;
}

            
findFor() public method

定义在: yii\db\ActiveRelationTrait::findFor()

查找指定主记录的相关记录。

当 ActiveRecord 的关系被延迟访问时,将调用此方法。

public mixed findFor ( $name, $model )
$name string

关系名称

$model yii\db\ActiveRecordInterface|yii\db\BaseActiveRecord

主模型

返回值 mixed

相关记录(可以是单一记录或多个记录)

抛出 yii\base\InvalidArgumentException

如果关系无效

                public function findFor($name, $model)
{
    if (method_exists($model, 'get' . $name)) {
        $method = new \ReflectionMethod($model, 'get' . $name);
        $realName = lcfirst(substr($method->getName(), 3));
        if ($realName !== $name) {
            throw new InvalidArgumentException('Relation names are case sensitive. ' . get_class($model) . " has a relation named \"$realName\" instead of \"$name\".");
        }
    }
    return $this->multiple ? $this->all() : $this->one();
}

            
findWith() public method

定义在: yii\db\ActiveQueryTrait::findWith()

查找与一个或多个关系相对应的记录,并将它们填充到主模型中。

public void findWith ( $with, &$models )
$with array

此查询应该执行的关联列表。有关如何指定此参数的详细信息,请参阅 with()

$models array|yii\db\ActiveRecord[]

主模型(可以是 AR 实例或数组)

                public function findWith($with, &$models)
{
    if (empty($models)) {
        return;
    }
    $primaryModel = reset($models);
    if (!$primaryModel instanceof ActiveRecordInterface) {
        /* @var $modelClass ActiveRecordInterface */
        $modelClass = $this->modelClass;
        $primaryModel = $modelClass::instance();
    }
    $relations = $this->normalizeRelations($primaryModel, $with);
    /* @var $relation ActiveQuery */
    foreach ($relations as $name => $relation) {
        if ($relation->asArray === null) {
            // inherit asArray from primary query
            $relation->asArray($this->asArray);
        }
        $relation->populateRelation($name, $models);
    }
}

            
from() public method

定义在: yii\db\Query::from()

设置查询的 FROM 部分。

public $this from ( $tables )
$tables string|array|yii\db\ExpressionInterface

要从中选择的表(或表)。这可以是字符串(例如 'user')或数组(例如 ['user', 'profile']),指定一个或多个表名。表名可以包含模式前缀(例如 'public.user')和/或表别名(例如 'user u')。此方法将自动引用表名,除非它包含一些括号(这意味着该表作为子查询或 DB 表达式给出)。

当表指定为数组时,您也可以使用数组键作为表别名(如果表不需要别名,则不要使用字符串键)。

使用 Query 对象来表示子查询。在这种情况下,对应的数组键将用作子查询的别名。

要以纯 SQL 指定 FROM 部分,可以传递 yii\db\ExpressionInterface 的实例。

以下是一些示例

// SELECT * FROM  `user` `u`, `profile`;
$query = (new \yii\db\Query)->from(['u' => 'user', 'profile']);

// SELECT * FROM (SELECT * FROM `user` WHERE `active` = 1) `activeusers`;
$subquery = (new \yii\db\Query)->from('user')->where(['active' => true])
$query = (new \yii\db\Query)->from(['activeusers' => $subquery]);

// subquery can also be a string with plain SQL wrapped in parenthesis
// SELECT * FROM (SELECT * FROM `user` WHERE `active` = 1) `activeusers`;
$subquery = "(SELECT * FROM `user` WHERE `active` = 1)";
$query = (new \yii\db\Query)->from(['activeusers' => $subquery]);
返回值 $this

查询对象本身

                public function from($tables)
{
    if ($tables instanceof ExpressionInterface) {
        $tables = [$tables];
    }
    if (is_string($tables)) {
        $tables = preg_split('/\s*,\s*/', trim($tables), -1, PREG_SPLIT_NO_EMPTY);
    }
    $this->from = $tables;
    return $this;
}

            
getBehavior() 公共方法

定义于: yii\base\Component::getBehavior()

返回命名的行为对象。

public yii\base\Behavior|null getBehavior ( $name )
$name string

行为名称

返回值 yii\base\Behavior|null

行为对象,如果行为不存在则为 null

                public function getBehavior($name)
{
    $this->ensureBehaviors();
    return isset($this->_behaviors[$name]) ? $this->_behaviors[$name] : null;
}

            
getBehaviors() 公共方法

定义于: yii\base\Component::getBehaviors()

返回附加到此组件的所有行为。

public yii\base\Behavior[] getBehaviors ( )
返回值 yii\base\Behavior[]

附加到此组件的行为列表

                public function getBehaviors()
{
    $this->ensureBehaviors();
    return $this->_behaviors;
}

            
getPrimaryTableName() 受保护方法 (自版本 2.0.12 起可用)

protected string getPrimaryTableName ( )
返回值 string

主表名

                protected function getPrimaryTableName()
{
    /* @var $modelClass ActiveRecord */
    $modelClass = $this->modelClass;
    return $modelClass::tableName();
}

            
getTableNameAndAlias() 受保护方法 (自版本 2.0.16 起可用)

返回 $modelClass 的表名和表别名。

protected array getTableNameAndAlias ( )
返回值 array

表名和表别名。

                protected function getTableNameAndAlias()
{
    if (empty($this->from)) {
        $tableName = $this->getPrimaryTableName();
    } else {
        $tableName = '';
        // if the first entry in "from" is an alias-tablename-pair return it directly
        foreach ($this->from as $alias => $tableName) {
            if (is_string($alias)) {
                return [$tableName, $alias];
            }
            break;
        }
    }
    if (preg_match('/^(.*?)\s+({{\w+}}|\w+)$/', $tableName, $matches)) {
        $alias = $matches[2];
    } else {
        $alias = $tableName;
    }
    return [$tableName, $alias];
}

            
getTablesUsedInFrom() 公共方法 (自版本 2.0.12 起可用)

返回 from() 中使用的表名,按别名索引。

别名和名称都包含在 {{ 和 }} 中。

public string[] getTablesUsedInFrom ( )
返回值 string[]

以别名作为索引的表名

抛出 yii\base\InvalidConfigException

                public function getTablesUsedInFrom()
{
    if (empty($this->from)) {
        return $this->cleanUpTableNames([$this->getPrimaryTableName()]);
    }
    return parent::getTablesUsedInFrom();
}

            
getUnaliasedColumnsFromSelect() 受保护方法 (自版本 2.0.14 起可用)
在 2.0.21 中已弃用
protected array getUnaliasedColumnsFromSelect ( )
返回值 array

来自 SELECT 语句的没有别名的列列表。

                protected function getUnaliasedColumnsFromSelect()
{
    $result = [];
    if (is_array($this->select)) {
        foreach ($this->select as $name => $value) {
            if (is_int($name)) {
                $result[] = $value;
            }
        }
    }
    return array_unique($result);
}

            
getUniqueColumns() 受保护方法 (自版本 2.0.14 起可用)
在 2.0.21 中已弃用

定义于: yii\db\Query::getUniqueColumns()

返回唯一的列名,排除重复项。

要删除的列

  • 如果列定义已存在于 SELECT 部分中,且别名相同
  • 如果列定义没有别名,并且在 SELECT 部分中也没有别名
protected void getUniqueColumns ( $columns )
$columns array

要合并到 select 的列。

                protected function getUniqueColumns($columns)
{
    $unaliasedColumns = $this->getUnaliasedColumnsFromSelect();
    $result = [];
    foreach ($columns as $columnAlias => $columnDefinition) {
        if (!$columnDefinition instanceof Query) {
            if (is_string($columnAlias)) {
                $existsInSelect = isset($this->select[$columnAlias]) && $this->select[$columnAlias] === $columnDefinition;
                if ($existsInSelect) {
                    continue;
                }
            } elseif (is_int($columnAlias)) {
                $existsInSelect = in_array($columnDefinition, $unaliasedColumns, true);
                $existsInResultSet = in_array($columnDefinition, $result, true);
                if ($existsInSelect || $existsInResultSet) {
                    continue;
                }
            }
        }
        $result[$columnAlias] = $columnDefinition;
    }
    return $result;
}

            
groupBy() 公共方法

定义于: yii\db\Query::groupBy()

设置查询的 GROUP BY 部分。

另见 addGroupBy()

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

要分组的列。列可以以字符串 (例如 "id, name") 或数组 (例如 ['id', 'name']) 指定。该方法将自动引用列名,除非列包含某些括号(这意味着列包含一个 DB 表达式)。

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

自版本 2.0.7 起,可以使用 yii\db\ExpressionInterface 对象以纯 SQL 显式指定 GROUP BY 部分。自版本 2.0.14 起,也可以使用 yii\db\ExpressionInterface 对象。

返回值 $this

查询对象本身

                public function groupBy($columns)
{
    if ($columns instanceof ExpressionInterface) {
        $columns = [$columns];
    } elseif (!is_array($columns) && !is_null($columns)) {
        $columns = preg_split('/\s*,\s*/', trim($columns), -1, PREG_SPLIT_NO_EMPTY);
    }
    $this->groupBy = $columns;
    return $this;
}

            
hasEventHandlers() 公共方法

定义于: yii\base\Component::hasEventHandlers()

返回一个值,指示是否有任何处理程序附加到命名的事件。

public boolean hasEventHandlers ( $name )
$name string

事件名称

返回值 boolean

是否有任何处理程序附加到该事件。

                public function hasEventHandlers($name)
{
    $this->ensureBehaviors();
    if (!empty($this->_events[$name])) {
        return true;
    }
    foreach ($this->_eventWildcards as $wildcard => $handlers) {
        if (!empty($handlers) && StringHelper::matchWildcard($wildcard, $name)) {
            return true;
        }
    }
    return Event::hasHandlers($this, $name);
}

            
hasMethod() 公共方法

定义于: yii\base\Component::hasMethod()

返回一个值,指示是否定义了方法。

如果定义了方法

  • 该类具有指定名称的方法
  • 附加的行为具有给定名称的方法(当 $checkBehaviors 为 true 时)。
public boolean hasMethod ( $name, $checkBehaviors true )
$name string

属性名称

$checkBehaviors boolean

是否将行为的方法视为此组件的方法

返回值 boolean

该方法是否已定义

                public function hasMethod($name, $checkBehaviors = true)
{
    if (method_exists($this, $name)) {
        return true;
    } elseif ($checkBehaviors) {
        $this->ensureBehaviors();
        foreach ($this->_behaviors as $behavior) {
            if ($behavior->hasMethod($name)) {
                return true;
            }
        }
    }
    return false;
}

            
hasProperty() 公共方法

定义于: yii\base\Component::hasProperty()

返回一个值,指示是否为此组件定义了属性。

如果定义了属性

  • 该类具有与指定名称关联的 getter 或 setter 方法(在这种情况下,属性名称不区分大小写);
  • 该类具有与指定名称相同的成员变量(当 $checkVars 为 true 时);
  • 附加的行为具有给定名称的属性(当 $checkBehaviors 为 true 时)。

另请参见

public boolean hasProperty ( $name, $checkVars true, $checkBehaviors true )
$name string

属性名称

$checkVars boolean

是否将成员变量视为属性

$checkBehaviors boolean

是否将行为的属性视为此组件的属性

返回值 boolean

该属性是否已定义

                public function hasProperty($name, $checkVars = true, $checkBehaviors = true)
{
    return $this->canGetProperty($name, $checkVars, $checkBehaviors) || $this->canSetProperty($name, false, $checkBehaviors);
}

            
having() 公共方法

定义于: yii\db\Query::having()

设置查询的 HAVING 部分。

另请参见

public $this having ( $condition, $params = [] )
$condition string|array|yii\db\ExpressionInterface

在 HAVING 后添加的条件。请参阅 where() 以了解如何指定此参数。

$params array

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

返回值 $this

查询对象本身

                public function having($condition, $params = [])
{
    $this->having = $condition;
    $this->addParams($params);
    return $this;
}

            
indexBy() 公共方法

定义于: yii\db\QueryTrait::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;
}

            
init() 公共方法

初始化对象。

此方法在构造函数结束时调用。默认实现将触发 EVENT_INIT 事件。如果您重写此方法,请确保在最后调用父实现以确保触发事件。

public void init ( )

                public function init()
{
    parent::init();
    $this->trigger(self::EVENT_INIT);
}

            
innerJoin() 公共方法

定义于: yii\db\Query::innerJoin()

将 INNER JOIN 部分追加到查询。

public $this innerJoin ( $table, $on '', $params = [] )
$table string|array

要连接的表或子查询。

使用字符串来表示要连接的表的名称。表名可以包含架构前缀(例如“public.user”)和/或表别名(例如“user u”)。该方法将自动引用表名,除非它包含一些括号(这意味着表被作为子查询或数据库表达式给出)。

您也可以使用包含一个元素的数组来指定表,使用数组键作为表别名(例如 ['u' => 'user'])。

要连接子查询,请使用包含一个元素的数组,将值设置为表示子查询的 yii\db\Query 对象,并将相应的键设置为别名。

$on string|array

应出现在 ON 部分中的连接条件。请参阅 join() 以了解如何指定此参数。

$params array

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

返回值 $this

查询对象本身

                public function innerJoin($table, $on = '', $params = [])
{
    $this->join[] = ['INNER JOIN', $table, $on];
    return $this->addParams($params);
}

            
innerJoinWith() 公共方法

与指定的关系进行内部联接。

这是 joinWith() 的快捷方法,将连接类型设置为“INNER JOIN”。请参阅 joinWith() 以了解此方法的详细用法。

另请参阅 joinWith()

public $this innerJoinWith ( $with, $eagerLoading true )
$with string|array

要连接的关系。

$eagerLoading boolean|array

是否急切加载关系。请注意,这并不意味着关系从查询结果中填充。仍然会执行额外的查询以引入相关数据。

返回值 $this

查询对象本身

                public function innerJoinWith($with, $eagerLoading = true)
{
    return $this->joinWith($with, $eagerLoading, 'INNER JOIN');
}

            
inverseOf() 公共方法

定义于: yii\db\ActiveRelationTrait::inverseOf()

设置与该关系相反的关系的名称。

例如,客户有订单,这意味着“订单”关系的逆关系是“客户”。如果设置了此属性,则主记录将通过指定的关系进行引用。例如,$customer->orders[0]->customer$customer 将是同一个对象,并且访问订单的客户将不会触发新的数据库查询。

yii\db\ActiveRecord 类中声明关系时使用此方法,例如在 Customer 模型中

public function getOrders()
{
    return $this->hasMany(Order::class, ['customer_id' => 'id'])->inverseOf('customer');
}

这也可以用于 Order 模型,但要谨慎

public function getCustomer()
{
    return $this->hasOne(Customer::class, ['id' => 'customer_id'])->inverseOf('orders');
}

在这种情况下,结果将取决于订单的加载方式。假设客户有几个订单。如果只加载了一个订单

$orders = Order::find()->where(['id' => 1])->all();
$customerOrders = $orders[0]->customer->orders;

变量 $customerOrders 将只包含一个订单。如果订单按以下方式加载

$orders = Order::find()->with('customer')->where(['customer_id' => 1])->all();
$customerOrders = $orders[0]->customer->orders;

变量 $customerOrders 将包含客户的所有订单。

public $this inverseOf ( $relationName )
$relationName string

此关系的逆关系的名称。

返回值 $this

关系对象本身。

                public function inverseOf($relationName)
{
    $this->inverseOf = $relationName;
    return $this;
}

            
isEmpty() 受保护方法

定义于: yii\db\QueryTrait::isEmpty()

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

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

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

如果该值为空

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

            
join() 公共方法

定义于: yii\db\Query::join()

将 JOIN 部分追加到查询。

第一个参数指定它是哪种类型的连接。

public $this join ( $type, $table, $on '', $params = [] )
$type string

连接的类型,例如 INNER JOIN、LEFT JOIN。

$table string|array

要连接的表或子查询。

使用字符串来表示要连接的表的名称。表名可以包含架构前缀(例如“public.user”)和/或表别名(例如“user u”)。该方法将自动引用表名,除非它包含一些括号(这意味着表被作为子查询或数据库表达式给出)。

您也可以使用包含一个元素的数组来指定表,使用数组键作为表别名(例如 ['u' => 'user'])。

要连接子查询,请使用包含一个元素的数组,将值设置为表示子查询的 yii\db\Query 对象,并将相应的键设置为别名。

$on string|array

应出现在 ON 部分中的连接条件。请参阅 where() 以了解如何指定此参数。

请注意,where() 的数组格式旨在将列匹配到值,而不是将列匹配到列,因此以下内容将不会按预期工作:['post.author_id' => 'user.id'],它会将 post.author_id 列值与字符串 'user.id' 匹配。建议在此处使用更适合连接的字符串语法

'post.author_id = user.id'
$params array

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

返回值 $this

查询对象本身

                public function join($type, $table, $on = '', $params = [])
{
    $this->join[] = [$type, $table, $on];
    return $this->addParams($params);
}

            
joinWith() 公共方法

与指定的关系进行联接。

此方法允许您重用现有的关系定义来执行 JOIN 查询。根据指定关系的定义,该方法将向当前查询追加一个或多个 JOIN 语句。

如果 $eagerLoading 参数为真,该方法还将对指定的关系执行急切加载,这等效于使用指定关系调用 with()

请注意,由于将执行 JOIN 查询,您有责任消除歧义列名。

此方法与 with() 不同,因为它将为主表构建和执行 JOIN SQL 语句。当 $eagerLoading 为真时,它还将使用指定关系调用 with()

public $this joinWith ( $with, $eagerLoading true, $joinType 'LEFT JOIN' )
$with string|array

要连接的关系。这可以是一个字符串,表示关系名称,也可以是一个包含以下语义的数组

  • 每个数组元素表示一个关系。
  • 您可以将关系名称指定为数组键,并提供一个匿名函数,该函数可以用来动态修改关系查询,作为数组值。
  • 如果关系查询不需要修改,您可以将关系名称用作数组值。

关系名称可以可选地包含关系表的别名(例如 books b)。

也可以指定子关系,有关语法,请参见 with()

以下是一些示例。

// find all orders that contain books, and eager loading "books"
Order::find()->joinWith('books', true, 'INNER JOIN')->all();
// find all orders, eager loading "books", and sort the orders and books by the book names.
Order::find()->joinWith([
    'books' => function (\yii\db\ActiveQuery $query) {
        $query->orderBy('item.name');
    }
])->all();
// find all orders that contain books of the category 'Science fiction', using the alias "b" for the books table
Order::find()->joinWith(['books b'], true, 'INNER JOIN')->where(['b.category' => 'Science fiction'])->all();

别名语法从 2.0.7 版本开始可用。

$eagerLoading boolean|array

是否急切加载在 $with 中指定的关联。当此参数为布尔值时,它应用于 $with 中指定的所有关联。使用数组显式列出 $with 中需要急切加载的关联。请注意,这并不意味着关联将从查询结果中填充。仍然需要执行额外的查询才能引入相关数据。默认值为 true

$joinType string|array

$with 中指定关联的连接类型。当此参数为字符串时,它应用于 $with 中指定的所有关联。使用 relationName => joinType 格式的数组为不同的关联指定不同的连接类型。

返回值 $this

查询对象本身

                public function joinWith($with, $eagerLoading = true, $joinType = 'LEFT JOIN')
{
    $relations = [];
    foreach ((array) $with as $name => $callback) {
        if (is_int($name)) {
            $name = $callback;
            $callback = null;
        }
        if (preg_match('/^(.*?)(?:\s+AS\s+|\s+)(\w+)$/i', $name, $matches)) {
            // relation is defined with an alias, adjust callback to apply alias
            list(, $relation, $alias) = $matches;
            $name = $relation;
            $callback = function ($query) use ($callback, $alias) {
                /* @var $query ActiveQuery */
                $query->alias($alias);
                if ($callback !== null) {
                    call_user_func($callback, $query);
                }
            };
        }
        if ($callback === null) {
            $relations[] = $name;
        } else {
            $relations[$name] = $callback;
        }
    }
    $this->joinWith[] = [$relations, $eagerLoading, $joinType];
    return $this;
}

            
leftJoin() 公共方法

定义于: yii\db\Query::leftJoin()

将 LEFT OUTER JOIN 部分追加到查询。

public $this leftJoin ( $table, $on '', $params = [] )
$table string|array

要连接的表或子查询。

使用字符串来表示要连接的表的名称。表名可以包含架构前缀(例如“public.user”)和/或表别名(例如“user u”)。该方法将自动引用表名,除非它包含一些括号(这意味着表被作为子查询或数据库表达式给出)。

您也可以使用包含一个元素的数组来指定表,使用数组键作为表别名(例如 ['u' => 'user'])。

要连接子查询,请使用包含一个元素的数组,将值设置为表示子查询的 yii\db\Query 对象,并将相应的键设置为别名。

$on string|array

应出现在 ON 部分中的连接条件。请参阅 join() 以了解如何指定此参数。

$params array

要绑定到查询的参数(名称 => 值)

返回值 $this

查询对象本身

                public function leftJoin($table, $on = '', $params = [])
{
    $this->join[] = ['LEFT JOIN', $table, $on];
    return $this->addParams($params);
}

            
limit() 公共方法

定义于: yii\db\QueryTrait::limit()

设置查询的 LIMIT 部分。

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

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

返回值 $this

查询对象本身

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

            
max() 公共方法

定义于: yii\db\Query::max()

返回指定列值的最大值。

public mixed max ( $q, $db null )
$q string

列名或表达式。确保您在表达式中正确 引用 列名。

$db yii\db\Connection|null

用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 db 应用程序组件。

返回值 mixed

指定列值的最大值。

                public function max($q, $db = null)
{
    return $this->queryScalar("MAX($q)", $db);
}

            
min() 公共方法

定义于: yii\db\Query::min()

返回指定列值的最小值。

public mixed min ( $q, $db null )
$q string

列名或表达式。确保您在表达式中正确 引用 列名。

$db yii\db\Connection|null

用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 db 应用程序组件。

返回值 mixed

指定列值的最小值。

                public function min($q, $db = null)
{
    return $this->queryScalar("MIN($q)", $db);
}

            
noCache() 公共方法 (从 2.0.14 版本开始可用)

定义于: yii\db\Query::noCache()

为此查询禁用查询缓存。

public $this noCache ( )
返回值 $this

查询对象本身

                public function noCache()
{
    $this->queryCacheDuration = -1;
    return $this;
}

            
normalizeOrderBy() 受保护方法

定义于: yii\db\QueryTrait::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;
}

            
normalizeSelect() 受保护方法 (从 2.0.21 版本开始可用)

定义于: yii\db\Query::normalizeSelect()

规范化传递给 select()addSelect() 的 SELECT 列。

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

                protected function normalizeSelect($columns)
{
    if ($columns instanceof ExpressionInterface) {
        $columns = [$columns];
    } elseif (!is_array($columns)) {
        $columns = preg_split('/\s*,\s*/', trim((string)$columns), -1, PREG_SPLIT_NO_EMPTY);
    }
    $select = [];
    foreach ($columns as $columnAlias => $columnDefinition) {
        if (is_string($columnAlias)) {
            // Already in the normalized format, good for them
            $select[$columnAlias] = $columnDefinition;
            continue;
        }
        if (is_string($columnDefinition)) {
            if (
                preg_match('/^(.*?)(?i:\s+as\s+|\s+)([\w\-_\.]+)$/', $columnDefinition, $matches) &&
                !preg_match('/^\d+$/', $matches[2]) &&
                strpos($matches[2], '.') === false
            ) {
                // Using "columnName as alias" or "columnName alias" syntax
                $select[$matches[2]] = $matches[1];
                continue;
            }
            if (strpos($columnDefinition, '(') === false) {
                // Normal column name, just alias it to itself to ensure it's not selected twice
                $select[$columnDefinition] = $columnDefinition;
                continue;
            }
        }
        // Either a string calling a function, DB expression, or sub-query
        $select[] = $columnDefinition;
    }
    return $select;
}

            
off() 公共方法

定义于: yii\base\Component::off()

从此组件分离现有的事件处理程序。

此方法是 on() 的反面。

注意:如果为事件名称传递通配符模式,则仅会删除使用此通配符注册的处理程序,而使用与通配符匹配的普通名称注册的处理程序将保留。

另请参阅 on()

public boolean off ( $name, $handler null )
$name string

事件名称

$handler callable|null

要删除的事件处理程序。如果它为 null,则将删除附加到指定事件的所有处理程序。

返回值 boolean

如果找到并分离了处理程序

                public function off($name, $handler = null)
{
    $this->ensureBehaviors();
    if (empty($this->_events[$name]) && empty($this->_eventWildcards[$name])) {
        return false;
    }
    if ($handler === null) {
        unset($this->_events[$name], $this->_eventWildcards[$name]);
        return true;
    }
    $removed = false;
    // plain event names
    if (isset($this->_events[$name])) {
        foreach ($this->_events[$name] as $i => $event) {
            if ($event[0] === $handler) {
                unset($this->_events[$name][$i]);
                $removed = true;
            }
        }
        if ($removed) {
            $this->_events[$name] = array_values($this->_events[$name]);
            return true;
        }
    }
    // wildcard event names
    if (isset($this->_eventWildcards[$name])) {
        foreach ($this->_eventWildcards[$name] as $i => $event) {
            if ($event[0] === $handler) {
                unset($this->_eventWildcards[$name][$i]);
                $removed = true;
            }
        }
        if ($removed) {
            $this->_eventWildcards[$name] = array_values($this->_eventWildcards[$name]);
            // remove empty wildcards to save future redundant regex checks:
            if (empty($this->_eventWildcards[$name])) {
                unset($this->_eventWildcards[$name]);
            }
        }
    }
    return $removed;
}

            
offset() 公共方法

定义于: yii\db\QueryTrait::offset()

设置查询的 OFFSET 部分。

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

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

返回值 $this

查询对象本身

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

            
on() 公共方法

定义于: yii\base\Component::on()

将事件处理程序附加到事件。

事件处理程序必须是有效的 PHP 回调。以下是一些示例

function ($event) { ... }         // anonymous function
[$object, 'handleClick']          // $object->handleClick()
['Page', 'handleClick']           // Page::handleClick()
'handleClick'                     // global function handleClick()

事件处理程序必须使用以下签名定义,

function ($event)

其中 $event 是一个 yii\base\Event 对象,其中包含与事件关联的参数。

从 2.0.14 版本开始,您可以将事件名称指定为通配符模式

$component->on('event.group.*', function ($event) {
    Yii::trace($event->name . ' is triggered.');
});

另请参阅 off()

public void on ( $name, $handler, $data null, $append true )
$name string

事件名称

$handler callable

事件处理程序

$data mixed

触发事件时传递给事件处理程序的数据。当事件处理程序被调用时,可以通过 yii\base\Event::$data 访问此数据。

$append boolean

是否将新的事件处理程序附加到现有处理程序列表的末尾。如果为 false,则新的处理程序将插入现有处理程序列表的开头。

                public function on($name, $handler, $data = null, $append = true)
{
    $this->ensureBehaviors();
    if (strpos($name, '*') !== false) {
        if ($append || empty($this->_eventWildcards[$name])) {
            $this->_eventWildcards[$name][] = [$handler, $data];
        } else {
            array_unshift($this->_eventWildcards[$name], [$handler, $data]);
        }
        return;
    }
    if ($append || empty($this->_events[$name])) {
        $this->_events[$name][] = [$handler, $data];
    } else {
        array_unshift($this->_events[$name], [$handler, $data]);
    }
}

            
onCondition() 公共方法

设置关系查询的 ON 条件。

当调用 yii\db\ActiveQuery::joinWith() 时,该条件将在 ON 部分使用。否则,该条件将在查询的 WHERE 部分使用。

使用此方法在 yii\db\ActiveRecord 类中声明关联时指定附加条件

public function getActiveUsers()
{
    return $this->hasMany(User::class, ['id' => 'user_id'])
                ->onCondition(['active' => true]);
}

请注意,此条件在连接的情况下以及获取相关记录时都会应用。因此,只有相关表的字段可以在条件中使用。尝试访问主记录的字段将在非连接查询中导致错误。

public $this onCondition ( $condition, $params [] )
$condition string|array

ON 条件。有关如何指定此参数的更多信息,请参阅 yii\db\Query::where()

$params array

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

返回值 $this

查询对象本身

                public function onCondition($condition, $params = [])
{
    $this->on = $condition;
    $this->addParams($params);
    return $this;
}

            
one() 公共方法

执行查询并返回一行结果。

public yii\db\ActiveRecord|array|null one ( $db null )
$db yii\db\Connection|null

用于创建 DB 命令的 DB 连接。如果为 null,则将使用 $modelClass 返回的 DB 连接。

返回值 yii\db\ActiveRecord|array|null

查询结果中的一行。根据 asArray() 的设置,查询结果可以是数组或 ActiveRecord 对象。 如果查询结果为空,则返回 null

                public function one($db = null)
{
    $row = parent::one($db);
    if ($row !== false) {
        $models = $this->populate([$row]);
        return reset($models) ?: null;
    }
    return null;
}

            
orFilterHaving() 公共方法 (从版本 2.0.11 开始可用)

定义于: yii\db\Query::orFilterHaving()

向现有的 HAVING 条件添加一个额外的 HAVING 条件,但忽略 空操作数

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

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

另请参见

public $this orFilterHaving ( array $condition )
$condition array

新的 HAVING 条件。有关如何指定此参数的信息,请参阅having()

返回值 $this

查询对象本身

                public function orFilterHaving(array $condition)
{
    $condition = $this->filterCondition($condition);
    if ($condition !== []) {
        $this->orHaving($condition);
    }
    return $this;
}

            
orFilterWhere() 公共方法

定义于: yii\db\QueryTrait::orFilterWhere()

向现有的 WHERE 条件添加一个额外的 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;
}

            
orHaving() 公共方法

定义于: yii\db\Query::orHaving()

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

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

另请参见

public $this orHaving ( $condition, $params = [] )
$condition string|array|yii\db\ExpressionInterface

新的 HAVING 条件。有关如何指定此参数的信息,请参阅where()

$params array

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

返回值 $this

查询对象本身

                public function orHaving($condition, $params = [])
{
    if ($this->having === null) {
        $this->having = $condition;
    } else {
        $this->having = ['or', $this->having, $condition];
    }
    $this->addParams($params);
    return $this;
}

            
orOnCondition() 公共方法

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

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

另请参见

public $this orOnCondition ( $condition, $params = [] )
$condition string|array

新的 ON 条件。有关如何指定此参数的信息,请参阅where()

$params array

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

返回值 $this

查询对象本身

                public function orOnCondition($condition, $params = [])
{
    if ($this->on === null) {
        $this->on = $condition;
    } else {
        $this->on = ['or', $this->on, $condition];
    }
    $this->addParams($params);
    return $this;
}

            
orWhere() 公共方法

定义于: yii\db\QueryTrait::orWhere()

向现有的 WHERE 条件添加一个额外的 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() 公共方法

定义于: yii\db\QueryTrait::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])指定。

除非列包含一些括号(这意味着列包含 DB 表达式),否则该方法将自动引用列名。

请注意,如果您的排序条件是一个包含逗号的表达式,则应始终使用数组来表示排序条件信息。否则,该方法将无法正确确定排序列。

从 2.0.7 版本开始,可以使用一个yii\db\ExpressionInterface 对象来明确地以纯 SQL 格式指定 ORDER BY 部分。

返回值 $this

查询对象本身

                public function orderBy($columns)
{
    $this->orderBy = $this->normalizeOrderBy($columns);
    return $this;
}

            
params() 公共方法

定义于: yii\db\Query::params()

设置要绑定到查询的参数。

另请参阅 addParams()

public $this params ( $params )
$params array

按参数占位符索引的查询参数值列表。例如,[':name' => 'Dan', ':age' => 31]

返回值 $this

查询对象本身

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

            
populate() 公共方法

将原始查询结果转换为此查询指定的格式。

此方法在内部用于将从数据库中获取的数据转换为此查询所需的格式。

public array populate ( $rows )
$rows array

来自数据库的原始查询结果

返回值 array

转换后的查询结果

                public function populate($rows)
{
    if (empty($rows)) {
        return [];
    }
    $models = $this->createModels($rows);
    if (!empty($this->join) && $this->indexBy === null) {
        $models = $this->removeDuplicatedModels($models);
    }
    if (!empty($this->with)) {
        $this->findWith($this->with, $models);
    }
    if ($this->inverseOf !== null) {
        $this->addInverseRelations($models);
    }
    if (!$this->asArray) {
        foreach ($models as $model) {
            $model->afterFind();
        }
    }
    return parent::populate($models);
}

            
populateRelation() 公共方法

定义于: yii\db\ActiveRelationTrait::populateRelation()

查找相关记录并将它们填充到主模型中。

public array populateRelation ( $name, &$primaryModels )
$name string

关系名称

$primaryModels array

主模型

返回值 array

相关模型

抛出 yii\base\InvalidConfigException

如果 $link 无效

                public function populateRelation($name, &$primaryModels)
{
    if (!is_array($this->link)) {
        throw new InvalidConfigException('Invalid link: it must be an array of key-value pairs.');
    }
    if ($this->via instanceof self) {
        // via junction table
        /* @var $viaQuery ActiveRelationTrait */
        $viaQuery = $this->via;
        $viaModels = $viaQuery->findJunctionRows($primaryModels);
        $this->filterByModels($viaModels);
    } elseif (is_array($this->via)) {
        // via relation
        /* @var $viaQuery ActiveRelationTrait|ActiveQueryTrait */
        list($viaName, $viaQuery) = $this->via;
        if ($viaQuery->asArray === null) {
            // inherit asArray from primary query
            $viaQuery->asArray($this->asArray);
        }
        $viaQuery->primaryModel = null;
        $viaModels = array_filter($viaQuery->populateRelation($viaName, $primaryModels));
        $this->filterByModels($viaModels);
    } else {
        $this->filterByModels($primaryModels);
    }
    if (!$this->multiple && count($primaryModels) === 1) {
        $model = $this->one();
        $primaryModel = reset($primaryModels);
        if ($primaryModel instanceof ActiveRecordInterface) {
            $primaryModel->populateRelation($name, $model);
        } else {
            $primaryModels[key($primaryModels)][$name] = $model;
        }
        if ($this->inverseOf !== null) {
            $this->populateInverseRelation($primaryModels, [$model], $name, $this->inverseOf);
        }
        return [$model];
    }
    // https://github.com/yiisoft/yii2/issues/3197
    // delay indexing related models after buckets are built
    $indexBy = $this->indexBy;
    $this->indexBy = null;
    $models = $this->all();
    if (isset($viaModels, $viaQuery)) {
        $buckets = $this->buildBuckets($models, $this->link, $viaModels, $viaQuery);
    } else {
        $buckets = $this->buildBuckets($models, $this->link);
    }
    $this->indexBy = $indexBy;
    if ($this->indexBy !== null && $this->multiple) {
        $buckets = $this->indexBuckets($buckets, $this->indexBy);
    }
    $link = array_values($this->link);
    if (isset($viaQuery)) {
        $deepViaQuery = $viaQuery;
        while ($deepViaQuery->via) {
            $deepViaQuery = is_array($deepViaQuery->via) ? $deepViaQuery->via[1] : $deepViaQuery->via;
        };
        $link = array_values($deepViaQuery->link);
    }
    foreach ($primaryModels as $i => $primaryModel) {
        $keys = null;
        if ($this->multiple && count($link) === 1) {
            $primaryModelKey = reset($link);
            $keys = isset($primaryModel[$primaryModelKey]) ? $primaryModel[$primaryModelKey] : null;
        }
        if (is_array($keys)) {
            $value = [];
            foreach ($keys as $key) {
                $key = $this->normalizeModelKey($key);
                if (isset($buckets[$key])) {
                    if ($this->indexBy !== null) {
                        // if indexBy is set, array_merge will cause renumbering of numeric array
                        foreach ($buckets[$key] as $bucketKey => $bucketValue) {
                            $value[$bucketKey] = $bucketValue;
                        }
                    } else {
                        $value = array_merge($value, $buckets[$key]);
                    }
                }
            }
        } else {
            $key = $this->getModelKey($primaryModel, $link);
            $value = isset($buckets[$key]) ? $buckets[$key] : ($this->multiple ? [] : null);
        }
        if ($primaryModel instanceof ActiveRecordInterface) {
            $primaryModel->populateRelation($name, $value);
        } else {
            $primaryModels[$i][$name] = $value;
        }
    }
    if ($this->inverseOf !== null) {
        $this->populateInverseRelation($primaryModels, $models, $name, $this->inverseOf);
    }
    return $models;
}

            
prepare() 公共方法

准备构建 SQL。

yii\db\QueryBuilder 开始从查询对象构建 SQL 时,会调用此方法。您可以重写此方法,在将查询转换为 SQL 语句时执行一些最终准备工作。

public $this prepare ( $builder )
$builder yii\db\QueryBuilder
返回值 $this

一个准备好的查询实例,将由 yii\db\QueryBuilder 用于构建 SQL

                public function prepare($builder)
{
    // NOTE: because the same ActiveQuery may be used to build different SQL statements
    // (e.g. by ActiveDataProvider, one for count query, the other for row data query,
    // it is important to make sure the same ActiveQuery can be used to build SQL statements
    // multiple times.
    if (!empty($this->joinWith)) {
        $this->buildJoinWith();
        $this->joinWith = null;    // clean it up to avoid issue https://github.com/yiisoft/yii2/issues/2687
    }
    if (empty($this->from)) {
        $this->from = [$this->getPrimaryTableName()];
    }
    if (empty($this->select) && !empty($this->join)) {
        list(, $alias) = $this->getTableNameAndAlias();
        $this->select = ["$alias.*"];
    }
    if ($this->primaryModel === null) {
        // eager loading
        $query = Query::create($this);
    } else {
        // lazy loading of a relation
        $where = $this->where;
        if ($this->via instanceof self) {
            // via junction table
            $viaModels = $this->via->findJunctionRows([$this->primaryModel]);
            $this->filterByModels($viaModels);
        } elseif (is_array($this->via)) {
            // via relation
            /* @var $viaQuery ActiveQuery */
            list($viaName, $viaQuery, $viaCallableUsed) = $this->via;
            if ($viaQuery->multiple) {
                if ($viaCallableUsed) {
                    $viaModels = $viaQuery->all();
                } elseif ($this->primaryModel->isRelationPopulated($viaName)) {
                    $viaModels = $this->primaryModel->$viaName;
                } else {
                    $viaModels = $viaQuery->all();
                    $this->primaryModel->populateRelation($viaName, $viaModels);
                }
            } else {
                if ($viaCallableUsed) {
                    $model = $viaQuery->one();
                } elseif ($this->primaryModel->isRelationPopulated($viaName)) {
                    $model = $this->primaryModel->$viaName;
                } else {
                    $model = $viaQuery->one();
                    $this->primaryModel->populateRelation($viaName, $model);
                }
                $viaModels = $model === null ? [] : [$model];
            }
            $this->filterByModels($viaModels);
        } else {
            $this->filterByModels([$this->primaryModel]);
        }
        $query = Query::create($this);
        $this->where = $where;
    }
    if (!empty($this->on)) {
        $query->andWhere($this->on);
    }
    return $query;
}

            
queryScalar() 保护方法

通过首先设置 select() 来查询标量值。

恢复 select 的值以使此查询可重复使用。

受保护 布尔值|字符串|空值 queryScalar ( $selectExpression, $db )
$selectExpression 字符串|yii\db\ExpressionInterface
$db yii\db\Connection|null

用于执行查询的数据库连接。

抛出 Throwable

如果无法创建命令

                protected function queryScalar($selectExpression, $db)
{
    /* @var $modelClass ActiveRecord */
    $modelClass = $this->modelClass;
    if ($db === null) {
        $db = $modelClass::getDb();
    }
    if ($this->sql === null) {
        return parent::queryScalar($selectExpression, $db);
    }
    $command = (new Query())->select([$selectExpression])
        ->from(['c' => "({$this->sql})"])
        ->params($this->params)
        ->createCommand($db);
    $this->setCommandCache($command);
    return $command->queryScalar();
}

            
rightJoin() 公共方法

定义于: yii\db\Query::rightJoin()

将 RIGHT OUTER JOIN 部分追加到查询。

public $this rightJoin ( $table, $on '', $params [] )
$table string|array

要连接的表或子查询。

使用字符串来表示要连接的表的名称。表名可以包含架构前缀(例如“public.user”)和/或表别名(例如“user u”)。该方法将自动引用表名,除非它包含一些括号(这意味着表被作为子查询或数据库表达式给出)。

您也可以使用包含一个元素的数组来指定表,使用数组键作为表别名(例如 ['u' => 'user'])。

要连接子查询,请使用包含一个元素的数组,将值设置为表示子查询的 yii\db\Query 对象,并将相应的键设置为别名。

$on string|array

应出现在 ON 部分中的连接条件。请参阅 join() 以了解如何指定此参数。

$params array

要绑定到查询的参数(名称 => 值)

返回值 $this

查询对象本身

                public function rightJoin($table, $on = '', $params = [])
{
    $this->join[] = ['RIGHT JOIN', $table, $on];
    return $this->addParams($params);
}

            
scalar() 公共方法

定义于: yii\db\Query::scalar()

将查询结果作为标量值返回。

返回的值将是查询结果的第一行中的第一列。

public 字符串|整数|空值|布尔值 scalar ( $db null )
$db yii\db\Connection|null

用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 db 应用程序组件。

返回值 字符串|整数|空值|布尔值

查询结果第一行第一列的值。如果查询结果为空,则返回 false。

                public function scalar($db = null)
{
    if ($this->emulateExecution) {
        return null;
    }
    return $this->createCommand($db)->queryScalar();
}

            
select() 公共方法

定义于: yii\db\Query::select()

设置查询的 SELECT 部分。

public $this select ( $columns, $option null )
$columns string|array|yii\db\ExpressionInterface

要选择的列。列可以用字符串(例如 "id, name")或数组(例如 ['id', 'name'])指定。列可以以表名前缀(例如 "user.id")和/或包含列别名(例如 "user.id AS user_id")。该方法会自动引用列名,除非列包含一些括号(这意味着列包含 DB 表达式)。DB 表达式也可以以 yii\db\ExpressionInterface 对象的形式传递。

注意,如果您选择的是像 CONCAT(first_name, ' ', last_name) 这样的表达式,您应该使用数组来指定列。否则,表达式可能会被错误地拆分为多个部分。

当列以数组形式指定时,您也可以使用数组键作为列别名(如果列不需要别名,则不要使用字符串键)。

从版本 2.0.1 开始,您也可以通过将每个这样的列指定为表示子查询的 Query 实例来选择子查询作为列。

$option string|null

应附加到 "SELECT" 关键字的额外选项。例如,在 MySQL 中,可以使用 "SQL_CALC_FOUND_ROWS" 选项。

返回值 $this

查询对象本身

                public function select($columns, $option = null)
{
    $this->select = $this->normalizeSelect($columns);
    $this->selectOption = $option;
    return $this;
}

            
setCommandCache() 受保护方法 (自版本 2.0.14 起可用)

定义于: yii\db\Query::setCommandCache()

设置 $command 缓存,如果此查询启用了缓存。

protected yii\db\Command setCommandCache ( $command )
$command yii\db\Command

                protected function setCommandCache($command)
{
    if ($this->queryCacheDuration !== null || $this->queryCacheDependency !== null) {
        $duration = $this->queryCacheDuration === true ? null : $this->queryCacheDuration;
        $command->cache($duration, $this->queryCacheDependency);
    }
    return $command;
}

            
sum() 公共方法

定义于: yii\db\Query::sum()

返回指定列值的总和。

public 混合 sum ( $q, $db null )
$q string

列名或表达式。确保您在表达式中正确 引用 列名。

$db yii\db\Connection|null

用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 db 应用程序组件。

返回值 mixed

指定列值的总和。

                public function sum($q, $db = null)
{
    if ($this->emulateExecution) {
        return 0;
    }
    return $this->queryScalar("SUM($q)", $db);
}

            
trigger() 公共方法

定义于: yii\base\Component::trigger()

触发事件。

此方法表示事件的发生。它调用所有附加到事件的处理程序,包括类级别处理程序。

public void trigger ( $name, yii\base\Event $event null )
$name string

事件名称

$event yii\base\Event|空值

事件实例。如果未设置,将创建默认的 yii\base\Event 对象。

                public function trigger($name, Event $event = null)
{
    $this->ensureBehaviors();
    $eventHandlers = [];
    foreach ($this->_eventWildcards as $wildcard => $handlers) {
        if (StringHelper::matchWildcard($wildcard, $name)) {
            $eventHandlers[] = $handlers;
        }
    }
    if (!empty($this->_events[$name])) {
        $eventHandlers[] = $this->_events[$name];
    }
    if (!empty($eventHandlers)) {
        $eventHandlers = call_user_func_array('array_merge', $eventHandlers);
        if ($event === null) {
            $event = new Event();
        }
        if ($event->sender === null) {
            $event->sender = $this;
        }
        $event->handled = false;
        $event->name = $name;
        foreach ($eventHandlers as $handler) {
            $event->data = $handler[1];
            call_user_func($handler[0], $event);
            // stop further handling if the event is handled
            if ($event->handled) {
                return;
            }
        }
    }
    // invoke class-level attached handlers
    Event::trigger($this, $name, $event);
}

            
union() 公共方法

定义于: yii\db\Query::union()

使用 UNION 运算符追加 SQL 语句。

public $this union ( $sql, $all false )
$sql 字符串|yii\db\Query

要使用 UNION 附加的 SQL 语句

$all boolean

如果使用 UNION ALL 则为 TRUE,如果使用 UNION 则为 FALSE

返回值 $this

查询对象本身

                public function union($sql, $all = false)
{
    $this->union[] = ['query' => $sql, 'all' => $all];
    return $this;
}

            
via() 公共方法

定义于: yii\db\ActiveRelationTrait::via()

指定与联接表关联的关系。

yii\db\ActiveRecord 类中声明关系时,使用此方法指定中间记录/表

class Order extends ActiveRecord
{
   public function getOrderItems() {
       return $this->hasMany(OrderItem::class, ['order_id' => 'id']);
   }

   public function getItems() {
       return $this->hasMany(Item::class, ['id' => 'item_id'])
                   ->via('orderItems');
   }
}
public $this via ( $relationName, 可调用 $callable null )
$relationName string

关系名称。这指的是在 $primaryModel 中声明的关系。

$callable callable|null

用于自定义与连接表关联的关系的 PHP 回调。它的签名应该是 function($query),其中 $query 是要自定义的查询。

返回值 $this

关系对象本身。

                public function via($relationName, callable $callable = null)
{
    $relation = $this->primaryModel->getRelation($relationName);
    $callableUsed = $callable !== null;
    $this->via = [$relationName, $relation, $callableUsed];
    if ($callable !== null) {
        call_user_func($callable, $relation);
    }
    return $this;
}

            
viaTable() 公共方法

为关系查询指定联接表。

yii\db\ActiveRecord 类中声明关系时,使用此方法指定连接表

public function getItems()
{
    return $this->hasMany(Item::class, ['id' => 'item_id'])
                ->viaTable('order_item', ['order_id' => 'id']);
}

另请参见 via()

public $this viaTable ( $tableName, $link, 可调用 $callable null )
$tableName string

连接表的名称。

$link array

连接表与与 $primaryModel 关联的表之间的链接。数组的键表示连接表中的列,值表示 $primaryModel 表中的列。

$callable callable|null

用于自定义与连接表关联的关系的 PHP 回调。它的签名应该是 function($query),其中 $query 是要自定义的查询。

返回值 $this

查询对象本身

抛出 yii\base\InvalidConfigException

当查询未正确初始化时

                public function viaTable($tableName, $link, callable $callable = null)
{
    $modelClass = $this->primaryModel ? get_class($this->primaryModel) : $this->modelClass;
    $relation = new self($modelClass, [
        'from' => [$tableName],
        'link' => $link,
        'multiple' => true,
        'asArray' => true,
    ]);
    $this->via = $relation;
    if ($callable !== null) {
        call_user_func($callable, $relation);
    }
    return $this;
}

            
where() 公共方法

定义于: yii\db\QueryTrait::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;
}

            
with() 公共方法

定义于: yii\db\ActiveQueryTrait::with()

指定应执行此查询的关系。

此方法的参数可以是一个或多个字符串,或者一个包含关系名称和可选回调的数组,用于自定义关系。

关系名称可以指 $modelClass 中定义的关系,或者代表关联记录关系的子关系。例如,orders.address 表示在对应于 orders 关系的模型类中定义的 address 关系。

以下是一些使用示例

// find customers together with their orders and country
Customer::find()->with('orders', 'country')->all();
// find customers together with their orders and the orders' shipping address
Customer::find()->with('orders.address')->all();
// find customers together with their country and orders of status 1
Customer::find()->with([
    'orders' => function (\yii\db\ActiveQuery $query) {
        $query->andWhere('status = 1');
    },
    'country',
])->all();

您可以多次调用 with()。每次调用都会将关系添加到现有关系中。例如,以下两个语句是等效的

Customer::find()->with('orders', 'country')->all();
Customer::find()->with('orders')->with('country')->all();
public $this with ( )
返回值 $this

查询对象本身

                public function with()
{
    $with = func_get_args();
    if (isset($with[0]) && is_array($with[0])) {
        // the parameter is given as an array
        $with = $with[0];
    }
    if (empty($this->with)) {
        $this->with = $with;
    } elseif (!empty($with)) {
        foreach ($with as $name => $value) {
            if (is_int($name)) {
                // repeating relation is fine as normalizeRelations() handle it well
                $this->with[] = $value;
            } else {
                $this->with[$name] = $value;
            }
        }
    }
    return $this;
}

            
withQuery() 公共方法 (从版本 2.0.35 开始可用)

定义于: yii\db\Query::withQuery()

使用 WITH 语法追加 SQL 语句。

public $this withQuery ( $query, $alias, $recursive false )
$query 字符串|yii\db\Query

使用 WITH 预先添加的 SQL 语句

$alias string

WITH 结构中的查询别名

$recursive boolean

如果使用 WITH RECURSIVE 则为 TRUE,如果使用 WITH 则为 FALSE

返回值 $this

查询对象本身

                public function withQuery($query, $alias, $recursive = false)
{
    $this->withQueries[] = ['query' => $query, 'alias' => $alias, 'recursive' => $recursive];
    return $this;
}

            

事件详细信息

隐藏继承的属性

EVENT_INIT 类型的事件 yii\db\Event

通过 init() 初始化查询时触发的事件。