Query.php 30 KB
Newer Older
w  
Qiang Xue committed
1 2 3
<?php
/**
 * @link http://www.yiiframework.com/
Qiang Xue committed
4
 * @copyright Copyright (c) 2008 Yii Software LLC
w  
Qiang Xue committed
5 6 7
 * @license http://www.yiiframework.com/license/
 */

Qiang Xue committed
8
namespace yii\db;
w  
Qiang Xue committed
9

10 11 12
use Yii;
use yii\base\Component;

w  
Qiang Xue committed
13
/**
Qiang Xue committed
14
 * Query represents a SELECT SQL statement in a way that is independent of DBMS.
Qiang Xue committed
15
 *
Qiang Xue committed
16 17
 * Query provides a set of methods to facilitate the specification of different clauses
 * in a SELECT statement. These methods can be chained together.
Qiang Xue committed
18
 *
Qiang Xue committed
19 20 21 22
 * By calling [[createCommand()]], we can get a [[Command]] instance which can be further
 * used to perform/execute the DB query against a database.
 *
 * For example,
Qiang Xue committed
23
 *
Carsten Brandt committed
24
 * ```php
Qiang Xue committed
25
 * $query = new Query;
Qiang Xue committed
26
 * // compose the query
Qiang Xue committed
27
 * $query->select('id, name')
28
 *     ->from('user')
Qiang Xue committed
29
 *     ->limit(10);
Qiang Xue committed
30
 * // build and execute the query
Qiang Xue committed
31 32
 * $rows = $query->all();
 * // alternatively, you can create DB command and execute it
Qiang Xue committed
33 34 35
 * $command = $query->createCommand();
 * // $command->sql returns the actual SQL
 * $rows = $command->queryAll();
Carsten Brandt committed
36
 * ```
Qiang Xue committed
37
 *
w  
Qiang Xue committed
38
 * @author Qiang Xue <qiang.xue@gmail.com>
39
 * @author Carsten Brandt <mail@cebe.cc>
w  
Qiang Xue committed
40 41
 * @since 2.0
 */
42
class Query extends Component implements QueryInterface
w  
Qiang Xue committed
43
{
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
    use QueryTrait;

    /**
     * @var array the columns being selected. For example, `['id', 'name']`.
     * This is used to construct the SELECT clause in a SQL statement. If not set, it means selecting all columns.
     * @see select()
     */
    public $select;
    /**
     * @var string additional option that should be appended to the 'SELECT' keyword. For example,
     * in MySQL, the option 'SQL_CALC_FOUND_ROWS' can be used.
     */
    public $selectOption;
    /**
     * @var boolean whether to select distinct rows of data only. If this is set true,
     * the SELECT clause would be changed to SELECT DISTINCT.
     */
    public $distinct;
    /**
63
     * @var array the table(s) to be selected from. For example, `['user', 'post']`.
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
     * This is used to construct the FROM clause in a SQL statement.
     * @see from()
     */
    public $from;
    /**
     * @var array how to group the query results. For example, `['company', 'department']`.
     * This is used to construct the GROUP BY clause in a SQL statement.
     */
    public $groupBy;
    /**
     * @var array how to join with other tables. Each array element represents the specification
     * of one join which has the following structure:
     *
     * ~~~
     * [$joinType, $tableName, $joinCondition]
     * ~~~
     *
     * For example,
     *
     * ~~~
     * [
85 86
     *     ['INNER JOIN', 'user', 'user.id = author_id'],
     *     ['LEFT JOIN', 'team', 'team.id = team_id'],
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
     * ]
     * ~~~
     */
    public $join;
    /**
     * @var string|array the condition to be applied in the GROUP BY clause.
     * It can be either a string or an array. Please refer to [[where()]] on how to specify the condition.
     */
    public $having;
    /**
     * @var array this is used to construct the UNION clause(s) in a SQL statement.
     * Each array element is an array of the following structure:
     *
     * - `query`: either a string or a [[Query]] object representing a query
     * - `all`: boolean, whether it should be `UNION ALL` or `UNION`
     */
    public $union;
    /**
     * @var array list of query parameter values indexed by parameter placeholders.
     * For example, `[':name' => 'Dan', ':age' => 31]`.
     */
    public $params = [];

Carsten Brandt committed
110

111 112
    /**
     * Creates a DB command that can be used to execute this query.
113 114 115
     * @param Connection $db the database connection used to generate the SQL statement.
     * If this parameter is not given, the `db` application component will be used.
     * @return Command the created DB command instance.
116 117 118 119 120 121 122 123 124 125 126
     */
    public function createCommand($db = null)
    {
        if ($db === null) {
            $db = Yii::$app->getDb();
        }
        list ($sql, $params) = $db->getQueryBuilder()->build($this);

        return $db->createCommand($sql, $params);
    }

Qiang Xue committed
127 128 129 130 131
    /**
     * Prepares for building SQL.
     * This method is called by [[QueryBuilder]] when it starts to build SQL from a query object.
     * You may override this method to do some final preparation work when converting a query into a SQL statement.
     * @param QueryBuilder $builder
132
     * @return Query a prepared query instance which will be used by [[QueryBuilder]] to build the SQL
Qiang Xue committed
133
     */
134
    public function prepare($builder)
Qiang Xue committed
135
    {
136
        return $this;
Qiang Xue committed
137 138
    }

139 140 141 142 143 144 145 146 147 148
    /**
     * Starts a batch query.
     *
     * A batch query supports fetching data in batches, which can keep the memory usage under a limit.
     * This method will return a [[BatchQueryResult]] object which implements the `Iterator` interface
     * and can be traversed to retrieve the data in batches.
     *
     * For example,
     *
     * ```php
149
     * $query = (new Query)->from('user');
150
     * foreach ($query->batch() as $rows) {
151
     *     // $rows is an array of 10 or fewer rows from user table
152 153 154
     * }
     * ```
     *
155 156
     * @param integer $batchSize the number of records to be fetched in each batch.
     * @param Connection $db the database connection. If not set, the "db" application component will be used.
157
     * @return BatchQueryResult the batch query result. It implements the `Iterator` interface
158
     * and can be traversed to retrieve the data in batches.
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
     */
    public function batch($batchSize = 100, $db = null)
    {
        return Yii::createObject([
            'class' => BatchQueryResult::className(),
            'query' => $this,
            'batchSize' => $batchSize,
            'db' => $db,
            'each' => false,
        ]);
    }

    /**
     * Starts a batch query and retrieves data row by row.
     * This method is similar to [[batch()]] except that in each iteration of the result,
     * only one row of data is returned. For example,
     *
     * ```php
177
     * $query = (new Query)->from('user');
178 179 180 181
     * foreach ($query->each() as $row) {
     * }
     * ```
     *
182 183
     * @param integer $batchSize the number of records to be fetched in each batch.
     * @param Connection $db the database connection. If not set, the "db" application component will be used.
184
     * @return BatchQueryResult the batch query result. It implements the `Iterator` interface
185
     * and can be traversed to retrieve the data in batches.
186 187 188 189 190 191 192 193 194 195 196 197 198 199
     */
    public function each($batchSize = 100, $db = null)
    {
        return Yii::createObject([
            'class' => BatchQueryResult::className(),
            'query' => $this,
            'batchSize' => $batchSize,
            'db' => $db,
            'each' => true,
        ]);
    }

    /**
     * Executes the query and returns all results as an array.
200 201 202
     * @param Connection $db the database connection used to generate the SQL statement.
     * If this parameter is not given, the `db` application component will be used.
     * @return array the query results. If the query results in nothing, an empty array will be returned.
203 204 205 206
     */
    public function all($db = null)
    {
        $rows = $this->createCommand($db)->queryAll();
207
        return $this->populate($rows);
208 209 210 211 212 213
    }

    /**
     * Converts the raw query results into the format as specified by this query.
     * This method is internally used to convert the data fetched from database
     * into the format as required by this query.
214
     * @param array $rows the raw query result from database
215 216
     * @return array the converted query result
     */
217
    public function populate($rows)
218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
    {
        if ($this->indexBy === null) {
            return $rows;
        }
        $result = [];
        foreach ($rows as $row) {
            if (is_string($this->indexBy)) {
                $key = $row[$this->indexBy];
            } else {
                $key = call_user_func($this->indexBy, $row);
            }
            $result[$key] = $row;
        }
        return $result;
    }

    /**
     * Executes the query and returns a single row of result.
236 237
     * @param Connection $db the database connection used to generate the SQL statement.
     * If this parameter is not given, the `db` application component will be used.
238
     * @return array|boolean the first row (in terms of an array) of the query result. False is returned if the query
239
     * results in nothing.
240 241 242 243 244 245 246 247 248
     */
    public function one($db = null)
    {
        return $this->createCommand($db)->queryOne();
    }

    /**
     * Returns the query result as a scalar value.
     * The value returned will be the first column in the first row of the query results.
249 250
     * @param Connection $db the database connection used to generate the SQL statement.
     * If this parameter is not given, the `db` application component will be used.
251
     * @return string|boolean the value of the first column in the first row of the query result.
252
     * False is returned if the query result is empty.
253 254 255 256 257 258 259 260
     */
    public function scalar($db = null)
    {
        return $this->createCommand($db)->queryScalar();
    }

    /**
     * Executes the query and returns the first column of the result.
261 262 263
     * @param Connection $db the database connection used to generate the SQL statement.
     * If this parameter is not given, the `db` application component will be used.
     * @return array the first column of the query result. An empty array is returned if the query results in nothing.
264 265 266 267 268 269 270 271
     */
    public function column($db = null)
    {
        return $this->createCommand($db)->queryColumn();
    }

    /**
     * Returns the number of records.
272 273 274 275 276
     * @param string $q the COUNT expression. Defaults to '*'.
     * Make sure you properly quote column names in the expression.
     * @param Connection $db the database connection used to generate the SQL statement.
     * If this parameter is not given (or null), the `db` application component will be used.
     * @return integer number of records
277 278 279 280 281 282 283 284
     */
    public function count($q = '*', $db = null)
    {
        return $this->queryScalar("COUNT($q)", $db);
    }

    /**
     * Returns the sum of the specified column values.
285 286 287 288
     * @param string $q the column name or expression.
     * Make sure you properly quote column names in the expression.
     * @param Connection $db the database connection used to generate the SQL statement.
     * If this parameter is not given, the `db` application component will be used.
289
     * @return mixed the sum of the specified column values
290 291 292 293 294 295 296 297
     */
    public function sum($q, $db = null)
    {
        return $this->queryScalar("SUM($q)", $db);
    }

    /**
     * Returns the average of the specified column values.
298 299 300 301
     * @param string $q the column name or expression.
     * Make sure you properly quote column names in the expression.
     * @param Connection $db the database connection used to generate the SQL statement.
     * If this parameter is not given, the `db` application component will be used.
302
     * @return mixed the average of the specified column values.
303 304 305 306 307 308 309 310
     */
    public function average($q, $db = null)
    {
        return $this->queryScalar("AVG($q)", $db);
    }

    /**
     * Returns the minimum of the specified column values.
311 312 313 314
     * @param string $q the column name or expression.
     * Make sure you properly quote column names in the expression.
     * @param Connection $db the database connection used to generate the SQL statement.
     * If this parameter is not given, the `db` application component will be used.
315
     * @return mixed the minimum of the specified column values.
316 317 318 319 320 321 322 323
     */
    public function min($q, $db = null)
    {
        return $this->queryScalar("MIN($q)", $db);
    }

    /**
     * Returns the maximum of the specified column values.
324 325 326 327
     * @param string $q the column name or expression.
     * Make sure you properly quote column names in the expression.
     * @param Connection $db the database connection used to generate the SQL statement.
     * If this parameter is not given, the `db` application component will be used.
328
     * @return mixed the maximum of the specified column values.
329 330 331 332 333 334 335 336
     */
    public function max($q, $db = null)
    {
        return $this->queryScalar("MAX($q)", $db);
    }

    /**
     * Returns a value indicating whether the query result contains any row of data.
337 338 339
     * @param Connection $db the database connection used to generate the SQL statement.
     * If this parameter is not given, the `db` application component will be used.
     * @return boolean whether the query result contains any row of data.
340 341 342 343 344 345 346 347 348 349 350 351 352
     */
    public function exists($db = null)
    {
        $select = $this->select;
        $this->select = [new Expression('1')];
        $command = $this->createCommand($db);
        $this->select = $select;
        return $command->queryScalar() !== false;
    }

    /**
     * Queries a scalar value by setting [[select]] first.
     * Restores the value of select to make this query reusable.
353 354
     * @param string|Expression $selectExpression
     * @param Connection|null $db
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371
     * @return bool|string
     */
    private function queryScalar($selectExpression, $db)
    {
        $select = $this->select;
        $limit = $this->limit;
        $offset = $this->offset;

        $this->select = [$selectExpression];
        $this->limit = null;
        $this->offset = null;
        $command = $this->createCommand($db);

        $this->select = $select;
        $this->limit = $limit;
        $this->offset = $offset;

372
        if (empty($this->groupBy) && empty($this->union) && !$this->distinct) {
373 374 375 376
            return $command->queryScalar();
        } else {
            return (new Query)->select([$selectExpression])
                ->from(['c' => $this])
377
                ->createCommand($command->db)
378 379 380 381 382 383 384
                ->queryScalar();
        }
    }

    /**
     * Sets the SELECT part of the query.
     * @param string|array $columns the columns to be selected.
385
     * Columns can be specified in either a string (e.g. "id, name") or an array (e.g. ['id', 'name']).
386
     * Columns can be prefixed with table names (e.g. "user.id") and/or contain column aliases (e.g. "user.id AS user_id").
387 388
     * The method will automatically quote the column names unless a column contains some parenthesis
     * (which means the column contains a DB expression).
389 390 391 392 393 394 395
     *
     * Note that if you are selecting an expression like `CONCAT(first_name, ' ', last_name)`, you should
     * use an array to specify the columns. Otherwise, the expression may be incorrectly split into several parts.
     *
     * When the columns are specified as an array, you may also use array keys as the column aliases (if a column
     * does not need alias, do not use a string key).
     *
396 397 398
     * Starting from version 2.0.1, you may also select sub-queries as columns by specifying each such column
     * as a `Query` instance representing the sub-query.
     *
399 400
     * @param string $option additional option that should be appended to the 'SELECT' keyword. For example,
     * in MySQL, the option 'SQL_CALC_FOUND_ROWS' can be used.
401 402 403 404 405 406 407 408 409 410 411 412
     * @return static the query object itself
     */
    public function select($columns, $option = null)
    {
        if (!is_array($columns)) {
            $columns = preg_split('/\s*,\s*/', trim($columns), -1, PREG_SPLIT_NO_EMPTY);
        }
        $this->select = $columns;
        $this->selectOption = $option;
        return $this;
    }

Alex-Code committed
413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431
    /**
     * Add more columns to the SELECT part of the query.
     * @param string|array $columns the columns to add to the select.
     * @return static the query object itself
     * @see select()
     */
    public function addSelect($columns)
    {
        if (!is_array($columns)) {
            $columns = preg_split('/\s*,\s*/', trim($columns), -1, PREG_SPLIT_NO_EMPTY);
        }
        if ($this->select === null) {
            $this->select = $columns;
        } else {
            $this->select = array_merge($this->select, $columns);
        }
        return $this;
    }

432 433
    /**
     * Sets the value indicating whether to SELECT DISTINCT or not.
434 435
     * @param boolean $value whether to SELECT DISTINCT or not.
     * @return static the query object itself
436 437 438 439 440 441 442 443 444
     */
    public function distinct($value = true)
    {
        $this->distinct = $value;
        return $this;
    }

    /**
     * Sets the FROM part of the query.
445 446 447
     * @param string|array $tables the table(s) to be selected from. This can be either a string (e.g. `'user'`)
     * or an array (e.g. `['user', 'profile']`) specifying one or several table names.
     * Table names can contain schema prefixes (e.g. `'public.user'`) and/or table aliases (e.g. `'user u'`).
448 449
     * The method will automatically quote the table names unless it contains some parenthesis
     * (which means the table is given as a sub-query or DB expression).
450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470
     *
     * When the tables are specified as an array, you may also use the array keys as the table aliases
     * (if a table does not need alias, do not use a string key).
     *
     * Use a Query object to represent a sub-query. In this case, the corresponding array key will be used
     * as the alias for the sub-query.
     *
     * @return static the query object itself
     */
    public function from($tables)
    {
        if (!is_array($tables)) {
            $tables = preg_split('/\s*,\s*/', trim($tables), -1, PREG_SPLIT_NO_EMPTY);
        }
        $this->from = $tables;
        return $this;
    }

    /**
     * Sets the WHERE part of the query.
     *
471
     * The method requires a `$condition` parameter, and optionally a `$params` parameter
472 473
     * specifying the values to be bound to the query.
     *
474
     * The `$condition` parameter should be either a string (e.g. `'id=1'`) or an array.
475
     *
476
     * @inheritdoc
477
     *
478 479 480
     * @param string|array $condition the conditions that should be put in the WHERE part.
     * @param array $params the parameters (name => value) to be bound to the query.
     * @return static the query object itself
481 482
     * @see andWhere()
     * @see orWhere()
483
     * @see QueryInterface::where()
484 485 486 487 488 489 490 491
     */
    public function where($condition, $params = [])
    {
        $this->where = $condition;
        $this->addParams($params);
        return $this;
    }

Alexander Makarov committed
492
    /**
493 494 495
     * Adds an additional WHERE condition to the existing one.
     * The new condition and the existing one will be joined using the 'AND' operator.
     * @param string|array $condition the new WHERE condition. Please refer to [[where()]]
Alexander Makarov committed
496 497 498
     * on how to specify this parameter.
     * @param array $params the parameters (name => value) to be bound to the query.
     * @return static the query object itself
499 500
     * @see where()
     * @see orWhere()
Alexander Makarov committed
501
     */
502
    public function andWhere($condition, $params = [])
Alexander Makarov committed
503
    {
504 505 506 507
        if ($this->where === null) {
            $this->where = $condition;
        } else {
            $this->where = ['and', $this->where, $condition];
Alexander Makarov committed
508
        }
509
        $this->addParams($params);
Alexander Makarov committed
510 511 512
        return $this;
    }

513 514
    /**
     * Adds an additional WHERE condition to the existing one.
515
     * The new condition and the existing one will be joined using the 'OR' operator.
516 517 518 519
     * @param string|array $condition the new WHERE condition. Please refer to [[where()]]
     * on how to specify this parameter.
     * @param array $params the parameters (name => value) to be bound to the query.
     * @return static the query object itself
520
     * @see where()
521
     * @see andWhere()
522
     */
523
    public function orWhere($condition, $params = [])
524 525 526 527
    {
        if ($this->where === null) {
            $this->where = $condition;
        } else {
528
            $this->where = ['or', $this->where, $condition];
529 530 531 532 533 534 535 536
        }
        $this->addParams($params);
        return $this;
    }

    /**
     * Appends a JOIN part to the query.
     * The first parameter specifies what type of join it is.
537
     * @param string $type the type of join, such as INNER JOIN, LEFT JOIN.
538 539 540
     * @param string|array $table the table to be joined.
     *
     * Use string to represent the name of the table to be joined.
541
     * Table name can contain schema prefix (e.g. 'public.user') and/or table alias (e.g. 'user u').
542 543 544 545 546 547 548
     * The method will automatically quote the table name unless it contains some parenthesis
     * (which means the table is given as a sub-query or DB expression).
     *
     * Use array to represent joining with a sub-query. The array must contain only one element.
     * The value must be a Query object representing the sub-query while the corresponding key
     * represents the alias for the sub-query.
     *
549 550 551 552
     * @param string|array $on the join condition that should appear in the ON part.
     * Please refer to [[where()]] on how to specify this parameter.
     * @param array $params the parameters (name => value) to be bound to the query.
     * @return Query the query object itself
553 554 555 556 557 558 559 560 561 562 563 564
     */
    public function join($type, $table, $on = '', $params = [])
    {
        $this->join[] = [$type, $table, $on];
        return $this->addParams($params);
    }

    /**
     * Appends an INNER JOIN part to the query.
     * @param string|array $table the table to be joined.
     *
     * Use string to represent the name of the table to be joined.
565
     * Table name can contain schema prefix (e.g. 'public.user') and/or table alias (e.g. 'user u').
566 567 568 569 570 571 572
     * The method will automatically quote the table name unless it contains some parenthesis
     * (which means the table is given as a sub-query or DB expression).
     *
     * Use array to represent joining with a sub-query. The array must contain only one element.
     * The value must be a Query object representing the sub-query while the corresponding key
     * represents the alias for the sub-query.
     *
573 574 575 576
     * @param string|array $on the join condition that should appear in the ON part.
     * Please refer to [[where()]] on how to specify this parameter.
     * @param array $params the parameters (name => value) to be bound to the query.
     * @return Query the query object itself
577 578 579 580 581 582 583 584 585 586 587 588
     */
    public function innerJoin($table, $on = '', $params = [])
    {
        $this->join[] = ['INNER JOIN', $table, $on];
        return $this->addParams($params);
    }

    /**
     * Appends a LEFT OUTER JOIN part to the query.
     * @param string|array $table the table to be joined.
     *
     * Use string to represent the name of the table to be joined.
589
     * Table name can contain schema prefix (e.g. 'public.user') and/or table alias (e.g. 'user u').
590 591 592 593 594 595 596
     * The method will automatically quote the table name unless it contains some parenthesis
     * (which means the table is given as a sub-query or DB expression).
     *
     * Use array to represent joining with a sub-query. The array must contain only one element.
     * The value must be a Query object representing the sub-query while the corresponding key
     * represents the alias for the sub-query.
     *
597 598 599 600
     * @param string|array $on the join condition that should appear in the ON part.
     * Please refer to [[where()]] on how to specify this parameter.
     * @param array $params the parameters (name => value) to be bound to the query
     * @return Query the query object itself
601 602 603 604 605 606 607 608 609 610 611 612
     */
    public function leftJoin($table, $on = '', $params = [])
    {
        $this->join[] = ['LEFT JOIN', $table, $on];
        return $this->addParams($params);
    }

    /**
     * Appends a RIGHT OUTER JOIN part to the query.
     * @param string|array $table the table to be joined.
     *
     * Use string to represent the name of the table to be joined.
613
     * Table name can contain schema prefix (e.g. 'public.user') and/or table alias (e.g. 'user u').
614 615 616 617 618 619 620
     * The method will automatically quote the table name unless it contains some parenthesis
     * (which means the table is given as a sub-query or DB expression).
     *
     * Use array to represent joining with a sub-query. The array must contain only one element.
     * The value must be a Query object representing the sub-query while the corresponding key
     * represents the alias for the sub-query.
     *
621 622 623 624
     * @param string|array $on the join condition that should appear in the ON part.
     * Please refer to [[where()]] on how to specify this parameter.
     * @param array $params the parameters (name => value) to be bound to the query
     * @return Query the query object itself
625 626 627 628 629 630 631 632 633
     */
    public function rightJoin($table, $on = '', $params = [])
    {
        $this->join[] = ['RIGHT JOIN', $table, $on];
        return $this->addParams($params);
    }

    /**
     * Sets the GROUP BY part of the query.
634 635 636 637 638
     * @param string|array $columns the columns to be grouped by.
     * Columns can be specified in either a string (e.g. "id, name") or an array (e.g. ['id', 'name']).
     * The method will automatically quote the column names unless a column contains some parenthesis
     * (which means the column contains a DB expression).
     * @return static the query object itself
639 640 641 642 643 644 645 646 647 648 649 650 651
     * @see addGroupBy()
     */
    public function groupBy($columns)
    {
        if (!is_array($columns)) {
            $columns = preg_split('/\s*,\s*/', trim($columns), -1, PREG_SPLIT_NO_EMPTY);
        }
        $this->groupBy = $columns;
        return $this;
    }

    /**
     * Adds additional group-by columns to the existing ones.
652 653 654 655 656
     * @param string|array $columns additional columns to be grouped by.
     * Columns can be specified in either a string (e.g. "id, name") or an array (e.g. ['id', 'name']).
     * The method will automatically quote the column names unless a column contains some parenthesis
     * (which means the column contains a DB expression).
     * @return static the query object itself
657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673
     * @see groupBy()
     */
    public function addGroupBy($columns)
    {
        if (!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;
    }

    /**
     * Sets the HAVING part of the query.
674 675 676 677
     * @param string|array $condition the conditions to be put after HAVING.
     * Please refer to [[where()]] on how to specify this parameter.
     * @param array $params the parameters (name => value) to be bound to the query.
     * @return static the query object itself
678 679 680 681 682 683 684 685 686 687 688 689 690
     * @see andHaving()
     * @see orHaving()
     */
    public function having($condition, $params = [])
    {
        $this->having = $condition;
        $this->addParams($params);
        return $this;
    }

    /**
     * Adds an additional HAVING condition to the existing one.
     * The new condition and the existing one will be joined using the 'AND' operator.
691 692 693 694
     * @param string|array $condition the new HAVING condition. Please refer to [[where()]]
     * on how to specify this parameter.
     * @param array $params the parameters (name => value) to be bound to the query.
     * @return static the query object itself
695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711
     * @see having()
     * @see orHaving()
     */
    public function andHaving($condition, $params = [])
    {
        if ($this->having === null) {
            $this->having = $condition;
        } else {
            $this->having = ['and', $this->having, $condition];
        }
        $this->addParams($params);
        return $this;
    }

    /**
     * Adds an additional HAVING condition to the existing one.
     * The new condition and the existing one will be joined using the 'OR' operator.
712 713 714 715
     * @param string|array $condition the new HAVING condition. Please refer to [[where()]]
     * on how to specify this parameter.
     * @param array $params the parameters (name => value) to be bound to the query.
     * @return static the query object itself
716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731
     * @see having()
     * @see andHaving()
     */
    public function orHaving($condition, $params = [])
    {
        if ($this->having === null) {
            $this->having = $condition;
        } else {
            $this->having = ['or', $this->having, $condition];
        }
        $this->addParams($params);
        return $this;
    }

    /**
     * Appends a SQL statement using UNION operator.
732 733 734
     * @param string|Query $sql the SQL statement to be appended using UNION
     * @param boolean $all TRUE if using UNION ALL and FALSE if using UNION
     * @return static the query object itself
735 736 737 738 739 740 741 742 743
     */
    public function union($sql, $all = false)
    {
        $this->union[] = [ 'query' => $sql, 'all' => $all ];
        return $this;
    }

    /**
     * Sets the parameters to be bound to the query.
744 745
     * @param array $params list of query parameter values indexed by parameter placeholders.
     * For example, `[':name' => 'Dan', ':age' => 31]`.
746 747 748 749 750 751 752 753 754 755 756
     * @return static the query object itself
     * @see addParams()
     */
    public function params($params)
    {
        $this->params = $params;
        return $this;
    }

    /**
     * Adds additional parameters to be bound to the query.
757 758
     * @param array $params list of query parameter values indexed by parameter placeholders.
     * For example, `[':name' => 'Dan', ':age' => 31]`.
759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778
     * @return static the query object itself
     * @see params()
     */
    public function addParams($params)
    {
        if (!empty($params)) {
            if (empty($this->params)) {
                $this->params = $params;
            } else {
                foreach ($params as $name => $value) {
                    if (is_integer($name)) {
                        $this->params[] = $value;
                    } else {
                        $this->params[$name] = $value;
                    }
                }
            }
        }
        return $this;
    }
779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804

    /**
     * Creates a new Query object and copies its property values from an existing one.
     * The properties being copies are the ones to be used by query builders.
     * @param Query $from the source query object
     * @return Query the new Query object
     */
    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,
        ]);
    }
w  
Qiang Xue committed
805
}