updated documentation and tests

docs/guide/db-query-builder.md

@@ -191,7 +191,7 @@ WHERE `id` IN (SELECT `id` FROM `user`)
 
 Another way to use the method is the operand format which is `[operator, operand1, operand2, ...]`.
 
-Operator can be one of the following:
+Operator can be one of the following (see also [[yii\db\QueryInterface::where()]]):
 
 - `and`: the operands should be concatenated together using `AND`. For example,
   `['and', 'id=1', 'id=2']` will generate `id=1 AND id=2`. If an operand is an array,

framework/db/QueryInterface.php

@@ -116,6 +116,12 @@ interface QueryInterface
      *   `['in', 'id', [1, 2, 3]]` will generate `id IN (1, 2, 3)`.
      *   The method will properly quote the column name and escape values in the range.
      *
+     *   To create a composite `IN` condition you can use and array for the column name and value, where the values are indexed by the column name:
+     *   `['in', ['id', 'name'], [['id' => 1, 'name' => 'foo'], ['id' => 2, 'name' => 'bar']] ]`.
+     *
+     *   You may also specify a sub-query that is used to get the values for the `IN`-condition:
+     *   `['in', 'user_id', (new Query())->select('id')->from('users')->where(['active' => 1])]`
+     *
      * - **not in**: similar to the `in` operator except that `IN` is replaced with `NOT IN` in the generated condition.
      *
      * - **like**: operand 1 should be a column or DB expression, and operand 2 be a string or an array representing
@@ -137,6 +143,12 @@ interface QueryInterface
      * - **or not like**: similar to the `not like` operator except that `OR` is used to concatenate
      *   the `NOT LIKE` predicates.
      *
+     * - **exists**: operand 1 is a query object that used to build an `EXISTS` condition. For example
+     *   `['exists', (new Query())->select('id')->from('users')->where(['active' => 1])]` will result in the following SQL expression:
+     *   `EXISTS (SELECT "id" FROM "users" WHERE "active"=1)`.
+     *
+     * - **not exists**: similar to the `exists` operator except that `EXISTS` is replaced with `NOT EXISTS` in the generated condition.
+     *
      * - Additionally you can specify arbitrary operators as follows: A condition of `['>=', 'id', 10]` will result in the
      *   following SQL expression: `id >= 10`.
      *

tests/unit/framework/db/QueryBuilderTest.php

@@ -171,8 +171,19 @@ class QueryBuilderTest extends DatabaseTestCase
             // in
             [ ['in', 'id', [1, 2, 3]], '"id" IN (:qp0, :qp1, :qp2)', [':qp0' => 1, ':qp1' => 2, ':qp2' => 3] ],
             [ ['not in', 'id', [1, 2, 3]], '"id" NOT IN (:qp0, :qp1, :qp2)', [':qp0' => 1, ':qp1' => 2, ':qp2' => 3] ],
+            [ ['in', 'id', (new Query())->select('id')->from('users')->where(['active' => 1])], '("id") IN (SELECT "id" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
+            [ ['not in', 'id', (new Query())->select('id')->from('users')->where(['active' => 1])], '("id") NOT IN (SELECT "id" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
 
-            // TODO: exists and not exists
+            // composite in
+            [ ['in', ['id', 'name'], [['id' => 1, 'name' => 'foo'], ['id' => 2, 'name' => 'bar']]], '("id", "name") IN ((:qp0, :qp1), (:qp2, :qp3))', [':qp0' => 1, ':qp1' => 'foo', ':qp2' => 2, ':qp3' => 'bar'] ],
+            [ ['not in', ['id', 'name'], [['id' => 1, 'name' => 'foo'], ['id' => 2, 'name' => 'bar']]], '("id", "name") NOT IN ((:qp0, :qp1), (:qp2, :qp3))', [':qp0' => 1, ':qp1' => 'foo', ':qp2' => 2, ':qp3' => 'bar'] ],
+            [ ['in', ['id', 'name'], (new Query())->select(['id', 'name'])->from('users')->where(['active' => 1])], '("id", "name") IN (SELECT "id", "name" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
+            [ ['not in', ['id', 'name'], (new Query())->select(['id', 'name'])->from('users')->where(['active' => 1])], '("id", "name") NOT IN (SELECT "id", "name" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
+
+
+            // exists
+            [ ['exists', (new Query())->select('id')->from('users')->where(['active' => 1])], 'EXISTS (SELECT "id" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
+            [ ['not exists', (new Query())->select('id')->from('users')->where(['active' => 1])], 'NOT EXISTS (SELECT "id" FROM "users" WHERE "active"=:qp0)', [':qp0' => 1] ],
 
             // simple conditions
             [ ['=', 'a', 'b'], '"a" = :qp0', [':qp0' => 'b'] ],
@@ -229,8 +240,6 @@ class QueryBuilderTest extends DatabaseTestCase
             [ ['in', 'id', []], '', [] ],
             [ ['not in', 'id', []], '', [] ],
 
-            // TODO: exists and not exists
-
             // simple conditions
             [ ['=', 'a', ''], '', [] ],
             [ ['>', 'a', ''], '', [] ],
@@ -262,8 +271,8 @@ class QueryBuilderTest extends DatabaseTestCase
     {
         $query = (new Query())->where($condition);
         list($sql, $params) = $this->getQueryBuilder()->build($query);
-        $this->assertEquals($expectedParams, $params);
         $this->assertEquals('SELECT *' . (empty($expected) ? '' : ' WHERE ' . $expected), $sql);
+        $this->assertEquals($expectedParams, $params);
     }
 
     /**
@@ -273,8 +282,8 @@ class QueryBuilderTest extends DatabaseTestCase
     {
         $query = (new Query())->filterWhere($condition);
         list($sql, $params) = $this->getQueryBuilder()->build($query);
-        $this->assertEquals($expectedParams, $params);
         $this->assertEquals('SELECT *' . (empty($expected) ? '' : ' WHERE ' . $expected), $sql);
+        $this->assertEquals($expectedParams, $params);
     }
 
     public function testAddDropPrimaryKey()
@@ -295,30 +304,28 @@ class QueryBuilderTest extends DatabaseTestCase
         $this->assertEquals(0, count($tableSchema->primaryKey));
     }
 
-    /* qiangxue: the following tests are commented because they vary by different DB drivers. need a better test scheme.
-    public function testBuildWhereExists()
+    public function existsParamsProvider()
     {
-        $expectedQuerySql = "SELECT `id` FROM `TotalExample` `t` WHERE EXISTS (SELECT `1` FROM `Website` `w`)";
-        $expectedQueryParams = null;
-
-        $subQuery = new Query();
-        $subQuery->select('1')
-            ->from('Website w');
-
-        $query = new Query();
-        $query->select('id')
-            ->from('TotalExample t')
-            ->where(['exists', $subQuery]);
+        $conditions = [
+            ['exists', "SELECT `id` FROM `TotalExample` `t` WHERE EXISTS (SELECT `1` FROM `Website` `w`)"],
+            ['not exists', "SELECT `id` FROM `TotalExample` `t` WHERE NOT EXISTS (SELECT `1` FROM `Website` `w`)"]
+        ];
 
-        list($actualQuerySql, $actualQueryParams) = $this->getQueryBuilder()->build($query);
-        $this->assertEquals($expectedQuerySql, $actualQuerySql);
-        $this->assertEquals($expectedQueryParams, $actualQueryParams);
+        // adjust dbms specific escaping
+        foreach($conditions as $i => $condition) {
+            if (!in_array($this->driverName, ['mssql', 'mysql', 'sqlite'])) {
+                $conditions[$i][1] = str_replace('`', '"', $condition[1]);
+            }
+        }
+        return $conditions;
     }
 
-    public function testBuildWhereNotExists()
+    /**
+     * @dataProvider existsParamsProvider
+     */
+    public function testBuildWhereExists($cond, $expectedQuerySql)
     {
-        $expectedQuerySql = "SELECT `id` FROM `TotalExample` `t` WHERE NOT EXISTS (SELECT `1` FROM `Website` `w`)";
-        $expectedQueryParams = null;
+        $expectedQueryParams = [];
 
         $subQuery = new Query();
         $subQuery->select('1')
@@ -327,16 +334,20 @@ class QueryBuilderTest extends DatabaseTestCase
         $query = new Query();
         $query->select('id')
             ->from('TotalExample t')
-            ->where(['not exists', $subQuery]);
+            ->where([$cond, $subQuery]);
 
         list($actualQuerySql, $actualQueryParams) = $this->getQueryBuilder()->build($query);
         $this->assertEquals($expectedQuerySql, $actualQuerySql);
         $this->assertEquals($expectedQueryParams, $actualQueryParams);
     }
 
+
     public function testBuildWhereExistsWithParameters()
     {
         $expectedQuerySql = "SELECT `id` FROM `TotalExample` `t` WHERE (EXISTS (SELECT `1` FROM `Website` `w` WHERE (w.id = t.website_id) AND (w.merchant_id = :merchant_id))) AND (t.some_column = :some_value)";
+        if (!in_array($this->driverName, ['mssql', 'mysql', 'sqlite'])) {
+            $expectedQuerySql = str_replace('`', '"', $expectedQuerySql);
+        }
         $expectedQueryParams = [':some_value' => "asd", ':merchant_id' => 6];
 
         $subQuery = new Query();
@@ -359,6 +370,9 @@ class QueryBuilderTest extends DatabaseTestCase
     public function testBuildWhereExistsWithArrayParameters()
     {
         $expectedQuerySql = "SELECT `id` FROM `TotalExample` `t` WHERE (EXISTS (SELECT `1` FROM `Website` `w` WHERE (w.id = t.website_id) AND ((`w`.`merchant_id`=:qp0) AND (`w`.`user_id`=:qp1)))) AND (`t`.`some_column`=:qp2)";
+        if (!in_array($this->driverName, ['mssql', 'mysql', 'sqlite'])) {
+            $expectedQuerySql = str_replace('`', '"', $expectedQuerySql);
+        }
         $expectedQueryParams = [':qp0' => 6, ':qp1' => 210, ':qp2' => 'asd'];
 
         $subQuery = new Query();
@@ -377,15 +391,17 @@ class QueryBuilderTest extends DatabaseTestCase
         $this->assertEquals($expectedQuerySql, $actualQuerySql);
         $this->assertEquals($expectedQueryParams, $queryParams);
     }
-    */
-
-    /*
-    This test contains three select queries connected with UNION and UNION ALL constructions.
-    It could be useful to use "phpunit --group=db --filter testBuildUnion" command for run it.
 
+    /**
+     * This test contains three select queries connected with UNION and UNION ALL constructions.
+     * It could be useful to use "phpunit --group=db --filter testBuildUnion" command for run it.
+     */
     public function testBuildUnion()
     {
-        $expectedQuerySql = "SELECT `id` FROM `TotalExample` `t1` WHERE (w > 0) AND (x < 2) UNION ( SELECT `id` FROM `TotalTotalExample` `t2` WHERE w > 5 ) UNION ALL ( SELECT `id` FROM `TotalTotalExample` `t3` WHERE w = 3 )";
+        $expectedQuerySql = "(SELECT `id` FROM `TotalExample` `t1` WHERE (w > 0) AND (x < 2)) UNION ( SELECT `id` FROM `TotalTotalExample` `t2` WHERE w > 5 ) UNION ALL ( SELECT `id` FROM `TotalTotalExample` `t3` WHERE w = 3 )";
+        if (!in_array($this->driverName, ['mssql', 'mysql', 'sqlite'])) {
+            $expectedQuerySql = str_replace('`', '"', $expectedQuerySql);
+        }
         $query = new Query();
         $secondQuery = new Query();
         $secondQuery->select('id')
@@ -402,5 +418,5 @@ class QueryBuilderTest extends DatabaseTestCase
               ->union($thirdQuery, TRUE);
         list($actualQuerySql, $queryParams) = $this->getQueryBuilder()->build($query);
         $this->assertEquals($expectedQuerySql, $actualQuerySql);
-     }*/
+    }
 }