0 追蹤者

特徵 yii\db\QueryTrait

所有類別 | 屬性 | 方法
實作於yii\db\ActiveQuery, yii\db\Query
自版本起可用2.0
原始碼 https://github.com/yiisoft/yii2/blob/master/framework/db/QueryTrait.php

BaseQuery 特徵代表資料庫查詢的最小方法集合。

它應該用於實作 yii\db\QueryInterface 的類別中。

公開屬性

隱藏繼承的屬性

屬性 類型 描述 定義於
$emulateExecution boolean 是否模擬實際的查詢執行，並返回空值或 false 結果。 yii\db\QueryTrait
$indexBy string|callable|null 應該用來索引查詢結果的欄位名稱。 yii\db\QueryTrait
$limit integer|yii\db\ExpressionInterface|null 要返回的最大記錄數。 yii\db\QueryTrait
$offset integer|yii\db\ExpressionInterface|null 從何處開始返回記錄的從零開始的偏移量。 yii\db\QueryTrait
$orderBy array|null 如何排序查詢結果。 yii\db\QueryTrait
$where string|array|yii\db\ExpressionInterface|null 查詢條件。 yii\db\QueryTrait

公開方法

隱藏繼承的方法

方法 描述 定義於
addOrderBy() 向查詢中添加額外的 ORDER BY 欄位。 yii\db\QueryTrait
andFilterWhere() 向現有的 WHERE 條件添加額外的條件，但忽略空運算元。 yii\db\QueryTrait
andWhere() 向現有的 WHERE 條件添加額外的條件。 yii\db\QueryTrait
emulateExecution() 設定是否模擬查詢執行，防止與資料儲存進行任何互動。 yii\db\QueryTrait
filterWhere() 設定查詢的 WHERE 部分，但忽略空運算元。 yii\db\QueryTrait
indexBy() 設定 indexBy() 屬性。 yii\db\QueryTrait
limit() 設定查詢的 LIMIT 部分。 yii\db\QueryTrait
offset() 設定查詢的 OFFSET 部分。 yii\db\QueryTrait
orFilterWhere() 向現有的 WHERE 條件添加額外的條件，但忽略空運算元。 yii\db\QueryTrait
orWhere() 向現有的 WHERE 條件添加額外的條件。 yii\db\QueryTrait
orderBy() 設定查詢的 ORDER BY 部分。 yii\db\QueryTrait
where() 設定查詢的 WHERE 部分。 yii\db\QueryTrait

保護方法

隱藏繼承的方法

方法 描述 定義於
filterCondition() 從給定的查詢條件中移除空運算元。 yii\db\QueryTrait
isEmpty() 返回一個值，指示給定值是否為「空」。 yii\db\QueryTrait
normalizeOrderBy() 正規化 ORDER BY 資料的格式。 yii\db\QueryTrait

屬性詳情

隱藏繼承的屬性

$emulateExecution 公開屬性 (自版本 2.0.11 起可用)

是否模擬實際的查詢執行，並返回空值或 false 結果。

另請參閱 emulateExecution()。

public boolean $emulateExecution = false
$indexBy 公開屬性

應該用來索引查詢結果的欄位名稱。這也可以是一個可呼叫的 (例如匿名函數)，根據給定的列資料返回索引值。 更多詳情，請參閱 indexBy()。 此屬性僅由 all() 使用。

public string|callable|null $indexBy = null
$limit 公開屬性

要返回的最大記錄數。可以是 yii\db\ExpressionInterface 的實例。如果未設定或小於 0，則表示沒有限制。

public integer|yii\db\ExpressionInterface|null $limit = null
$offset 公開屬性

從何處開始返回記錄的從零開始的偏移量。可以是 yii\db\ExpressionInterface 的實例。如果未設定或小於 0，則表示從頭開始。

public integer|yii\db\ExpressionInterface|null $offset = null
$orderBy 公開屬性

如何排序查詢結果。這用於在 SQL 語句中建構 ORDER BY 子句。陣列鍵是要排序的欄位，而陣列值是對應的排序方向，可以是 SORT_ASC 或 SORT_DESC。 陣列也可能包含 yii\db\ExpressionInterface 物件。 在這種情況下，表達式將轉換為字串，而不會有任何變更。

public array|null $orderBy = null
$where 公開屬性

查詢條件。這指的是 SQL 語句中的 WHERE 子句。 例如，['age' => 31, 'team' => 1]。

有關指定此值的有效語法，另請參閱 where()。

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

方法詳情

隱藏繼承的方法

addOrderBy() 公開方法

向查詢中添加額外的 ORDER BY 欄位。

另請參閱 orderBy()。

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

要排序依據的欄位 (和方向)。 欄位可以指定為字串 (例如 "id ASC, name DESC") 或陣列 (例如 ['id' => SORT_ASC, 'name' => SORT_DESC])。

除非欄位包含一些括號 (表示欄位包含 DB 表達式)，否則此方法將自動引用欄位名稱。

請注意，如果您的 order-by 是一個包含逗號的表達式，您應該始終使用陣列來表示 order-by 資訊。 否則，此方法將無法正確判斷 order-by 欄位。

自版本 2.0.7 起，可以傳遞 yii\db\ExpressionInterface 物件，以純 SQL 顯式指定 ORDER BY 部分。
return $this

查詢物件本身

 

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

向現有的 WHERE 條件添加額外的條件，但忽略空運算元。

新條件和現有條件將使用 'AND' 運算子連接。

此方法與 andWhere() 類似。 主要區別在於此方法將移除空查詢運算元。 因此，此方法最適合用於根據使用者輸入的篩選值來建構查詢條件。

另請參閱

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

新的 WHERE 條件。 有關如何指定此參數，請參閱 where()。
return $this

查詢物件本身

 

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

向現有的 WHERE 條件添加額外的條件。

新條件和現有條件將使用 'AND' 運算子連接。

另請參閱

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

新的 WHERE 條件。 有關如何指定此參數，請參閱 where()。
return $this

查詢物件本身

 

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

設定是否模擬查詢執行，防止與資料儲存進行任何互動。

啟用此模式後，返回查詢結果的方法，例如 yii\db\QueryInterface::one()、yii\db\QueryInterface::all()、yii\db\QueryInterface::exists() 等等，將返回空值或 false 值。 如果您的程式邏輯指示查詢不應返回任何結果，例如在您設定像 0=1 這樣的 false where 條件的情況下，您應該使用此方法。

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

是否防止查詢執行。
return $this

查詢物件本身。

 

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

從給定的查詢條件中移除空運算元。

protected array filterCondition ( $condition )
$condition array

原始條件
return array

移除空運算元後的條件。
throws yii\base\NotSupportedException

如果條件運算子不受支援

 

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

設定查詢的 WHERE 部分，但忽略空運算元。

此方法與 where() 類似。 主要區別在於此方法將移除空查詢運算元。 因此，此方法最適合用於根據使用者輸入的篩選值來建構查詢條件。

以下程式碼顯示了此方法與 where() 之間的差異

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

請注意，與 where() 不同，您無法將繫結參數傳遞給此方法。

另請參閱

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

應放入 WHERE 部分的條件。 有關如何指定此參數，請參閱 where()。
return $this

查詢物件本身

 

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

設定 indexBy() 屬性。

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

應該用來索引查詢結果的欄位名稱。 這也可以是一個可呼叫的 (例如匿名函數)，根據給定的列資料返回索引值。 可呼叫的簽名應為

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

查詢物件本身

 

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

返回一個值，指示給定值是否為「空」。

如果滿足以下條件之一，則該值被視為「空」

  • 它是 null，
  • 一個空字串 ('')，
  • 一個僅包含空格字元的字串，
  • 或一個空陣列。
protected boolean isEmpty ( $value )
$value mixed
return boolean

如果值為空

 

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

設定查詢的 LIMIT 部分。

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

限制。 使用 null 或負值來停用限制。
return $this

查詢物件本身

 

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

正規化 ORDER BY 資料的格式。

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

要正規化的欄位值。 請參閱 orderBy() 和 addOrderBy()。

 

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

設定查詢的 OFFSET 部分。

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

偏移量。 使用 null 或負值來停用偏移量。
return $this

查詢物件本身

 

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

向現有的 WHERE 條件添加額外的條件，但忽略空運算元。

新條件和現有條件將使用 'OR' 運算子連接。

此方法與 orWhere() 類似。 主要區別在於此方法將移除空查詢運算元。 因此，此方法最適合用於根據使用者輸入的篩選值來建構查詢條件。

另請參閱

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

新的 WHERE 條件。 有關如何指定此參數，請參閱 where()。
return $this

查詢物件本身

 

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

向現有的 WHERE 條件添加額外的條件。

新條件和現有條件將使用 'OR' 運算子連接。

另請參閱

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

新的 WHERE 條件。 有關如何指定此參數，請參閱 where()。
return $this

查詢物件本身

 

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

設定查詢的 ORDER BY 部分。

另請參閱 addOrderBy()。

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

要排序依據的欄位 (和方向)。 欄位可以指定為字串 (例如 "id ASC, name DESC") 或陣列 (例如 ['id' => SORT_ASC, 'name' => SORT_DESC])。

除非欄位包含一些括號 (表示欄位包含 DB 表達式)，否則此方法將自動引用欄位名稱。

請注意，如果您的 order-by 是一個包含逗號的表達式，您應該始終使用陣列來表示 order-by 資訊。 否則，此方法將無法正確判斷 order-by 欄位。

自版本 2.0.7 起，可以傳遞 yii\db\ExpressionInterface 物件，以純 SQL 顯式指定 ORDER BY 部分。
return $this

查詢物件本身

 

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

設定查詢的 WHERE 部分。

有關詳細文件，請參閱 yii\db\QueryInterface::where()。

另請參閱

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

應放入 WHERE 部分的條件。
return $this

查詢物件本身

 

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