トレイト 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 | クエリ結果をインデックス付ける列の名前。与えられた行データに基づいてインデックス値を返すcallable（例：無名関数）も指定できます。indexBy()を参照ください。このプロパティはall()によってのみ使用されます。 | yii\db\QueryTrait |
| $limit | integer|yii\db\ExpressionInterface|null | 返されるレコードの最大数。 | yii\db\QueryTrait |
| $offset | integer|yii\db\ExpressionInterface|null | 0から始まる、レコードを返す開始位置。 | 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 |
プロパティの詳細
実際のクエリ実行をエミュレートし、空の結果またはfalseを返すかどうか。
emulateExecution()も参照してください。
返されるレコードの最大数。yii\db\ExpressionInterfaceのインスタンスも指定できます。設定されていないか、0以下の場合は、制限なしを意味します。
0から始まる、レコードを返す開始位置。yii\db\ExpressionInterfaceのインスタンスも指定できます。設定されていないか、0以下の場合は、先頭から開始することを意味します。
クエリ結果のソート方法を指定します。これは、SQL文のORDER BY句を構築するために使用されます。配列のキーはソート対象の列名、値はソート順で、SORT_ASCまたはSORT_DESCを指定できます。yii\db\ExpressionInterfaceオブジェクトを含めることもできます。その場合、式は変更なしで文字列に変換されます。
メソッドの詳細
クエリに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オブジェクトを渡して、ORDER BY部分をプレーンなSQLで明示的に指定できます。 |
| 戻り値 | $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;
}
既存の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 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\QueryInterface::one()、yii\db\QueryInterface::all()、yii\db\QueryInterface::exists()など、クエリ結果を返すメソッドは、空の値またはfalseを返します。 `0=1` のようなfalseとなる条件を設定した場合など、プログラムロジックでクエリが結果を返す必要がない場合に、このメソッドを使用する必要があります。
| public $this emulateExecution ( $value = true ) | ||
| $value | boolean |
クエリの実行を防止するかどうか。 |
| 戻り値 | $this |
クエリオブジェクト自体。 |
|---|---|---|
public function emulateExecution($value = true)
{
$this->emulateExecution = $value;
return $this;
}
与えられたクエリ条件から空のオペランドを削除します。
| 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;
}
WHERE句を設定しますが、空のオペランドは無視します。
このメソッドはwhere()に似ています。主な違いは、このメソッドが空のクエリオペランドを削除することです。そのため、このメソッドはユーザーが入力したフィルタ値に基づいてクエリ条件を構築するのに最適です。
次のコードは、このメソッドとwhere()の違いを示しています。
// WHERE `age`=:age
$query->filterWhere(['name' => null, 'age' => 20]);
// WHERE `age`=:age
$query->where(['age' => 20]);
// WHERE `name` IS NULL AND `age`=:age
$query->where(['name' => null, 'age' => 20]);
where()とは異なり、このメソッドにはバインディングパラメータを渡すことができません。
こちらも参照
| public $this filterWhere ( array $condition ) | ||
| $condition | array |
WHERE句に追加する条件。where()でこのパラメータの指定方法を参照してください。 |
| 戻り値 | $this |
クエリオブジェクト自体 |
|---|---|---|
public function filterWhere(array $condition)
{
$condition = $this->filterCondition($condition);
if ($condition !== []) {
$this->where($condition);
}
return $this;
}
indexBy()プロパティを設定します。
| public $this indexBy ( $column ) | ||
| $column | string|callable |
クエリ結果をインデックスするために使用する列の名前。これは、指定された行データに基づいてインデックス値を返すコールバック関数（例：無名関数）にすることもできます。コールバック関数のシグネチャは次のようになります。 |
| 戻り値 | $this |
クエリオブジェクト自体 |
|---|---|---|
public function indexBy($column)
{
$this->indexBy = $column;
return $this;
}
与えられた値が「空」かどうかを示す値を返します。
以下の条件のいずれかが満たされた場合、値は「空」とみなされます。
nullである場合、- 空文字列（
''）である場合、 - 空白文字のみを含む文字列である場合、
- 空の配列である場合。
| protected boolean isEmpty ( $value ) | ||
| $value | 混合型 | |
| 戻り値 | boolean |
値が空の場合 |
|---|---|---|
protected function isEmpty($value)
{
return $value === '' || $value === [] || $value === null || is_string($value) && trim($value) === '';
}
クエリのLIMIT句を設定します。
| public $this limit ( $limit ) | ||
| $limit | integer|yii\db\ExpressionInterface|null |
制限数。制限を無効にするには、nullまたは負の値を使用します。 |
| 戻り値 | $this |
クエリオブジェクト自体 |
|---|---|---|
public function limit($limit)
{
$this->limit = $limit;
return $this;
}
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句を設定します。
| public $this offset ( $offset ) | ||
| $offset | integer|yii\db\ExpressionInterface|null |
オフセット。オフセットを無効にするには、nullまたは負の値を使用します。 |
| 戻り値 | $this |
クエリオブジェクト自体 |
|---|---|---|
public function offset($offset)
{
$this->offset = $offset;
return $this;
}
既存の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;
}
| 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;
}
クエリのORDER BY句を設定します。
addOrderBy()も参照してください。
| public $this orderBy ( $columns ) | ||
| $columns | string|array|yii\db\ExpressionInterface|null |
ソート順序を指定する列（と方向）。列は、文字列（例： 列名に括弧が含まれていない限り（DB式を含む場合）、メソッドは自動的に列名を引用符で囲みます。 カンマを含む式でソートする場合、常に配列を使用してソート情報を表す必要があります。そうでない場合、メソッドはソート列を正しく判別できません。 バージョン2.0.7以降、yii\db\ExpressionInterfaceオブジェクトを渡して、ORDER BY部分をプレーンなSQLで明示的に指定できます。 |
| 戻り値 | $this |
クエリオブジェクト自体 |
|---|---|---|
public function orderBy($columns)
{
$this->orderBy = $this->normalizeOrderBy($columns);
return $this;
}
コメントするにはサインアップまたはログインしてください。