类 yii\db\ActiveQuery
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(),它添加一个要添加到关系查询联接条件的条件。
公共属性
公共方法
受保护方法
方法 | 描述 | 定义者 |
---|---|---|
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 |
属性详细信息
当此查询在关系上下文中使用时要使用的联接条件。当调用 yii\db\ActiveQuery::joinWith() 时,该条件将在 ON 部分中使用。否则,该条件将在查询的 WHERE 部分中使用。有关如何指定此参数的详细信息,请参考 yii\db\Query::where()。
另请参阅 onCondition()。
用于检索 AR 记录要执行的 SQL 语句。由 yii\db\ActiveRecord::findBySql() 设置。
方法详细信息
定义于: 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()");
}
定义于: 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]];
}
}
构造函数。
public void __construct ( $modelClass, $config = [] ) | ||
$modelClass | string |
与该查询关联的模型类 |
$config | array |
要应用于新创建的查询对象的配置 |
public function __construct($modelClass, $config = [])
{
$this->modelClass = $modelClass;
parent::__construct($config);
}
定义于: 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);
}
定义于: yii\base\Component::__isset()
检查属性是否已设置,即定义且不为空。
此方法将按照以下顺序检查并相应地执行
- 由 setter 定义的属性:返回属性是否已设置
- 行为的属性:返回属性是否已设置
- 对于不存在的属性返回
false
不要直接调用此方法,因为它是一个 PHP 魔术方法,当执行 isset($component->property)
时会隐式调用。
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;
}
定义于: 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);
}
定义于: yii\db\Query::__toString()
返回查询的 SQL 表示形式
public string __toString ( ) |
public function __toString()
{
return serialize($this);
}
定义于: yii\base\Component::__unset()
将组件属性设置为 null。
此方法将按照以下顺序检查并相应地执行
- 由 setter 定义的属性:将属性值设置为 null
- 行为的属性:将属性值设置为 null
不要直接调用此方法,因为它是一个 PHP 魔术方法,当执行 unset($component->property)
时会隐式调用。
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);
}
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;
}
public $this addOrderBy ( $columns ) | ||
$columns | string|array|yii\db\ExpressionInterface |
要排序的列(以及方向)。列可以以字符串(例如“id ASC, name 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;
}
public $this addParams ( $params ) | ||
$params | array |
按参数占位符索引的查询参数值列表。例如, |
返回值 | $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;
}
定义于: 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;
}
为在 $modelClass 中定义的表定义别名。
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;
}
执行查询并以数组形式返回所有结果。
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);
}
定义于: yii\db\Query::andFilterCompare()
为特定列添加过滤条件,并允许用户选择过滤运算符。
它为给定字段添加一个额外的 WHERE 条件,并根据给定值的开头几个字符确定比较运算符。条件以与andFilterWhere() 中相同的方式添加,因此空值 将被忽略。新条件和现有条件将使用AND
运算符连接。
比较运算符是根据给定值中的开头几个字符智能地确定的。特别是,它会识别以下运算符,如果它们作为给定值的开头字符出现
<
:列必须小于给定值。>
:列必须大于给定值。<=
:列必须小于或等于给定值。>=
:列必须大于或等于给定值。<>
:列不能与给定值相同。=
:列必须等于给定值。- 如果未检测到上述任何运算符,则将使用
$defaultOperator
。
public $this andFilterCompare ( $name, $value, $defaultOperator = '=' ) | ||
$name | string |
列名。 |
$value | string |
列值,可选地以比较运算符为前缀。 |
$defaultOperator | string |
当 |
返回值 | $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]);
}
定义于: 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;
}
定义于: 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;
}
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;
}
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;
}
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;
}
定义于: yii\db\ActiveQueryTrait::asArray()
设置 asArray() 属性。
public $this asArray ( $value = true ) | ||
$value | boolean |
是否以数组形式而不是活动记录的形式返回查询结果。 |
返回值 | $this |
查询对象本身 |
---|
public function asArray($value = true)
{
$this->asArray = $value;
return $this;
}
定义于: 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);
}
定义于: 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);
}
}
返回指定列值的平均值。
public mixed average ( $q, $db = null ) | ||
$q | string |
列名或表达式。确保您在表达式中正确 引用 列名。 |
$db | yii\db\Connection|null |
用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 |
返回值 | mixed |
指定列值的平均值。 |
---|
public function average($q, $db = null)
{
if ($this->emulateExecution) {
return 0;
}
return $this->queryScalar("AVG($q)", $db);
}
开始批量查询。
批量查询支持分批获取数据,这可以将内存使用量控制在一定范围内。此方法将返回一个 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,
]);
}
定义于: yii\base\Component::behaviors()
返回此组件应表现为的行为列表。
子类可以重写此方法来指定它们希望表现的行为。
此方法的返回值应为行为对象或配置的数组,这些对象或配置由行为名称索引。行为配置可以是指定行为类的字符串,也可以是以下结构的数组
'behaviorName' => [
'class' => 'BehaviorClass',
'property1' => 'value1',
'property2' => 'value2',
]
请注意,行为类必须扩展自 yii\base\Behavior。行为可以使用名称或匿名方式附加。当使用名称作为数组键时,使用此名称,行为稍后可以使用 getBehavior() 检索,或使用 detachBehavior() 分离。匿名行为不能检索或分离。
在此方法中声明的行为将自动附加到组件(按需)。
public array behaviors ( ) | ||
返回值 | array |
行为配置。 |
---|
public function behaviors()
{
return [];
}
为此查询启用查询缓存。
public $this cache ( $duration = true, $dependency = null ) | ||
$duration | integer|true |
查询结果可以在缓存中保持有效的秒数。使用 0 表示缓存的数据永不过期。使用负数表示不应使用查询缓存。使用布尔值 |
$dependency | yii\caching\Dependency|null |
与缓存结果关联的缓存依赖项。 |
返回值 | $this |
查询对象本身 |
---|
public function cache($duration = true, $dependency = null)
{
$this->queryCacheDuration = $duration;
$this->queryCacheDependency = $dependency;
return $this;
}
定义于: 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;
}
定义于: 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;
}
::class
。
定义于: yii\base\BaseObject::className()
返回此类的完全限定名称。
public static string className ( ) | ||
返回值 | string |
此类的完全限定名称。 |
---|
public static function className()
{
return get_called_class();
}
定义于: 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;
}
执行查询并返回结果的第一列。
public array column ( $db = null ) | ||
$db | yii\db\Connection|null |
用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 |
返回值 | 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;
}
返回记录数量。
public integer|string|null count ( $q = '*', $db = null ) | ||
$q | string |
COUNT 表达式。默认值为 '*'. 确保您在表达式中正确 引用 列名。 |
$db | yii\db\Connection|null |
用于生成 SQL 语句的数据库连接。如果此参数未给出(或为 null),则将使用 |
返回值 | integer|string|null |
记录数量。结果可能是一个字符串,具体取决于底层数据库引擎,以支持高于 32 位 PHP 整数所能处理的整数。 |
---|
public function count($q = '*', $db = null)
{
if ($this->emulateExecution) {
return 0;
}
return $this->queryScalar("COUNT($q)", $db);
}
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,
]);
}
创建一个可以用于执行此查询的 DB 命令。
public yii\db\Command createCommand ( $db = null ) | ||
$db | yii\db\Connection|null |
用于创建 DB 命令的 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;
}
定义于: 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;
}
}
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;
}
定义于: yii\base\Component::detachBehaviors()
从组件分离所有行为。
public void detachBehaviors ( ) |
public function detachBehaviors()
{
$this->ensureBehaviors();
foreach ($this->_behaviors as $name => $behavior) {
$this->detachBehavior($name);
}
}
设置指示是否选择 DISTINCT 的值。
public $this distinct ( $value = true ) | ||
$value | boolean |
是否选择 DISTINCT 或不选择 DISTINCT。 |
返回值 | $this |
查询对象本身 |
---|
public function distinct($value = true)
{
$this->distinct = $value;
return $this;
}
定义在: 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,
]);
}
定义在: 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;
}
定义在: 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);
}
}
}
返回一个值,指示查询结果是否包含任何数据行。
public boolean exists ( $db = null ) | ||
$db | yii\db\Connection|null |
用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 |
返回值 | 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();
}
定义在: 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;
}
定义在: 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;
}
定义在: 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;
}
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();
}
定义在: 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);
}
}
定义在: yii\db\Query::from()
设置查询的 FROM 部分。
public $this from ( $tables ) | ||
$tables | string|array|yii\db\ExpressionInterface |
要从中选择的表(或表)。这可以是字符串(例如 当表指定为数组时,您也可以使用数组键作为表别名(如果表不需要别名,则不要使用字符串键)。 使用 Query 对象来表示子查询。在这种情况下,对应的数组键将用作子查询的别名。 要以纯 SQL 指定 以下是一些示例
|
返回值 | $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;
}
定义于: 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;
}
定义于: yii\base\Component::getBehaviors()
返回附加到此组件的所有行为。
public yii\base\Behavior[] getBehaviors ( ) | ||
返回值 | yii\base\Behavior[] |
附加到此组件的行为列表 |
---|
public function getBehaviors()
{
$this->ensureBehaviors();
return $this->_behaviors;
}
protected string getPrimaryTableName ( ) | ||
返回值 | string |
主表名 |
---|
protected function getPrimaryTableName()
{
/* @var $modelClass ActiveRecord */
$modelClass = $this->modelClass;
return $modelClass::tableName();
}
返回 $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];
}
返回 from() 中使用的表名,按别名索引。
别名和名称都包含在 {{ 和 }} 中。
public string[] getTablesUsedInFrom ( ) | ||
返回值 | string[] |
以别名作为索引的表名 |
---|---|---|
抛出 | yii\base\InvalidConfigException |
public function getTablesUsedInFrom()
{
if (empty($this->from)) {
return $this->cleanUpTableNames([$this->getPrimaryTableName()]);
}
return parent::getTablesUsedInFrom();
}
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);
}
定义于: 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;
}
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;
}
定义于: 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);
}
定义于: 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;
}
定义于: 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);
}
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;
}
定义于: yii\db\QueryTrait::indexBy()
设置 indexBy() 属性。
public $this indexBy ( $column ) | ||
$column | string|callable |
要通过其对查询结果进行索引的列的名称。这也可以是可调用函数(例如匿名函数),它根据给定的行数据返回索引值。可调用函数的签名应为
|
返回值 | $this |
查询对象本身 |
---|
public function indexBy($column)
{
$this->indexBy = $column;
return $this;
}
初始化对象。
此方法在构造函数结束时调用。默认实现将触发 EVENT_INIT 事件。如果您重写此方法,请确保在最后调用父实现以确保触发事件。
public void init ( ) |
public function init()
{
parent::init();
$this->trigger(self::EVENT_INIT);
}
定义于: 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);
}
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');
}
定义于: 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;
}
定义于: 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) === '';
}
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() 的数组格式旨在将列匹配到值,而不是将列匹配到列,因此以下内容将不会按预期工作:
|
$params | array |
要绑定到查询的参数(name => value)。 |
返回值 | $this |
查询对象本身 |
---|
public function join($type, $table, $on = '', $params = [])
{
$this->join[] = [$type, $table, $on];
return $this->addParams($params);
}
与指定的关系进行联接。
此方法允许您重用现有的关系定义来执行 JOIN 查询。根据指定关系的定义,该方法将向当前查询追加一个或多个 JOIN 语句。
如果 $eagerLoading
参数为真,该方法还将对指定的关系执行急切加载,这等效于使用指定关系调用 with()。
请注意,由于将执行 JOIN 查询,您有责任消除歧义列名。
此方法与 with() 不同,因为它将为主表构建和执行 JOIN SQL 语句。当 $eagerLoading
为真时,它还将使用指定关系调用 with()。
public $this joinWith ( $with, $eagerLoading = true, $joinType = 'LEFT JOIN' ) | ||
$with | string|array |
要连接的关系。这可以是一个字符串,表示关系名称,也可以是一个包含以下语义的数组
关系名称可以可选地包含关系表的别名(例如 也可以指定子关系,有关语法,请参见 with()。 以下是一些示例。
别名语法从 2.0.7 版本开始可用。 |
$eagerLoading | boolean|array |
是否急切加载在 |
$joinType | string|array |
|
返回值 | $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;
}
将 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);
}
定义于: 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;
}
定义于: yii\db\Query::max()
返回指定列值的最大值。
public mixed max ( $q, $db = null ) | ||
$q | string |
列名或表达式。确保您在表达式中正确 引用 列名。 |
$db | yii\db\Connection|null |
用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 |
返回值 | mixed |
指定列值的最大值。 |
---|
public function max($q, $db = null)
{
return $this->queryScalar("MAX($q)", $db);
}
定义于: yii\db\Query::min()
返回指定列值的最小值。
public mixed min ( $q, $db = null ) | ||
$q | string |
列名或表达式。确保您在表达式中正确 引用 列名。 |
$db | yii\db\Connection|null |
用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 |
返回值 | mixed |
指定列值的最小值。 |
---|
public function min($q, $db = null)
{
return $this->queryScalar("MIN($q)", $db);
}
为此查询禁用查询缓存。
public $this noCache ( ) | ||
返回值 | $this |
查询对象本身 |
---|
public function noCache()
{
$this->queryCacheDuration = -1;
return $this;
}
定义于: 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;
}
定义于: 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;
}
定义于: 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;
}
定义于: 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;
}
将事件处理程序附加到事件。
事件处理程序必须是有效的 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]);
}
}
设置关系查询的 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;
}
执行查询并返回一行结果。
public yii\db\ActiveRecord|array|null one ( $db = null ) | ||
$db | yii\db\Connection|null |
用于创建 DB 命令的 DB 连接。如果为 |
返回值 | yii\db\ActiveRecord|array|null |
查询结果中的一行。根据 asArray() 的设置,查询结果可以是数组或 ActiveRecord 对象。 如果查询结果为空,则返回 |
---|
public function one($db = null)
{
$row = parent::one($db);
if ($row !== false) {
$models = $this->populate([$row]);
return reset($models) ?: null;
}
return null;
}
定义于: 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;
}
定义于: 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;
}
向现有的 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;
}
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;
}
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;
}
public $this orderBy ( $columns ) | ||
$columns | string|array|yii\db\ExpressionInterface|null |
要排序的列(和方向)。列可以使用字符串(例如 除非列包含一些括号(这意味着列包含 DB 表达式),否则该方法将自动引用列名。 请注意,如果您的排序条件是一个包含逗号的表达式,则应始终使用数组来表示排序条件信息。否则,该方法将无法正确确定排序列。 从 2.0.7 版本开始,可以使用一个yii\db\ExpressionInterface 对象来明确地以纯 SQL 格式指定 ORDER BY 部分。 |
返回值 | $this |
查询对象本身 |
---|
public function orderBy($columns)
{
$this->orderBy = $this->normalizeOrderBy($columns);
return $this;
}
public $this params ( $params ) | ||
$params | array |
按参数占位符索引的查询参数值列表。例如, |
返回值 | $this |
查询对象本身 |
---|
public function params($params)
{
$this->params = $params;
return $this;
}
将原始查询结果转换为此查询指定的格式。
此方法在内部用于将从数据库中获取的数据转换为此查询所需的格式。
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);
}
定义于: 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;
}
准备构建 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;
}
通过首先设置 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();
}
定义于: 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);
}
public 字符串|整数|空值|布尔值 scalar ( $db = null ) | ||
$db | yii\db\Connection|null |
用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 |
返回值 | 字符串|整数|空值|布尔值 |
查询结果第一行第一列的值。如果查询结果为空,则返回 false。 |
---|
public function scalar($db = null)
{
if ($this->emulateExecution) {
return null;
}
return $this->createCommand($db)->queryScalar();
}
设置查询的 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 对象的形式传递。 注意,如果您选择的是像 当列以数组形式指定时,您也可以使用数组键作为列别名(如果列不需要别名,则不要使用字符串键)。 从版本 2.0.1 开始,您也可以通过将每个这样的列指定为表示子查询的 |
$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;
}
定义于: 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;
}
定义于: yii\db\Query::sum()
返回指定列值的总和。
public 混合 sum ( $q, $db = null ) | ||
$q | string |
列名或表达式。确保您在表达式中正确 引用 列名。 |
$db | yii\db\Connection|null |
用于生成 SQL 语句的数据库连接。如果未给出此参数,将使用 |
返回值 | mixed |
指定列值的总和。 |
---|
public function sum($q, $db = null)
{
if ($this->emulateExecution) {
return 0;
}
return $this->queryScalar("SUM($q)", $db);
}
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 运算符追加 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;
}
定义于: 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 回调。它的签名应该是 |
返回值 | $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;
}
为关系查询指定联接表。
在 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 回调。它的签名应该是 |
返回值 | $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;
}
public $this where ( $condition ) | ||
$condition | string|array|yii\db\ExpressionInterface |
应该放在 WHERE 部分中的条件。 |
返回值 | $this |
查询对象本身 |
---|
public function where($condition)
{
$this->where = $condition;
return $this;
}
定义于: 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;
}
定义于: 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;
}
注册 或 登录 以评论。