renamed Query::filter() to Query::filterWhere()

extensions/gii/generators/crud/Generator.php

@@ -400,10 +400,10 @@ class Generator extends \yii\gii\Generator
                 case Schema::TYPE_TIME:
                 case Schema::TYPE_DATETIME:
                 case Schema::TYPE_TIMESTAMP:
-                    $conditions[] = "\$query->andFilter(['{$column}' => \$this->{$column}]);";
+                    $conditions[] = "\$query->andFilterWhere(['{$column}' => \$this->{$column}]);";
                     break;
                 default:
-                    $conditions[] = "\$this->addFilter(['like', '{$column}', \$this->{$column}]);";
+                    $conditions[] = "\$this->andFilterWhere(['like', '{$column}', \$this->{$column}]);";
                     break;
             }
         }

extensions/sphinx/Query.php

@@ -466,7 +466,6 @@ class Query extends Component implements QueryInterface
     {
         $this->where = $condition;
         $this->addParams($params);
-
         return $this;
     }
 
@@ -480,13 +479,12 @@ class Query extends Component implements QueryInterface
      * @see andFilter()
      * @see orFilter()
      */
-    public function filter($condition, $params = [])
+    public function filterWhere($condition, $params = [])
     {
         $condition = $this->filterCondition($condition);
         if ($condition !== []) {
             $this->where($condition, $params);
         }
-
         return $this;
     }
 
@@ -508,7 +506,6 @@ class Query extends Component implements QueryInterface
             $this->where = ['and', $this->where, $condition];
         }
         $this->addParams($params);
-
         return $this;
     }
 
@@ -523,13 +520,12 @@ class Query extends Component implements QueryInterface
      * @see filter()
      * @see orFilter()
      */
-    public function andFilter($condition, $params = [])
+    public function andFilterWhere($condition, $params = [])
     {
         $condition = $this->filterCondition($condition);
         if ($condition !== []) {
             $this->andWhere($condition, $params);
         }
-
         return $this;
     }
 
@@ -551,7 +547,6 @@ class Query extends Component implements QueryInterface
             $this->where = ['or', $this->where, $condition];
         }
         $this->addParams($params);
-
         return $this;
     }
 
@@ -566,13 +561,12 @@ class Query extends Component implements QueryInterface
      * @see filter()
      * @see andFilter()
      */
-    public function orFilter($condition, $params = [])
+    public function orFilterWhere($condition, $params = [])
     {
         $condition = $this->filterCondition($condition);
         if ($condition !== []) {
             $this->orWhere($condition, $params);
         }
-
         return $this;
     }
 
@@ -824,7 +818,7 @@ class Query extends Component implements QueryInterface
                 case 'OR':
                     for ($i = 1, $operandsCount = count($condition); $i < $operandsCount; $i++) {
                         $subCondition = $this->filterCondition($condition[$i]);
-                        if ($this->parameterNotEmpty($subCondition)) {
+                        if ($this->isParameterNotEmpty($subCondition)) {
                             $condition[$i] = $subCondition;
                         } else {
                             unset($condition[$i]);
@@ -848,13 +842,13 @@ class Query extends Component implements QueryInterface
                 case 'OR LIKE':
                 case 'NOT LIKE':
                 case 'OR NOT LIKE':
-                    if (!$this->parameterNotEmpty($condition[2])) {
+                    if (!$this->isParameterNotEmpty($condition[2])) {
                         $condition = [];
                     }
                 break;
                 case 'BETWEEN':
                 case 'NOT BETWEEN':
-                    if (!$this->parameterNotEmpty($condition[2]) && !$this->parameterNotEmpty($condition[3])) {
+                    if (!$this->isParameterNotEmpty($condition[2]) && !$this->isParameterNotEmpty($condition[3])) {
                         $condition = [];
                     }
                 break;

framework/db/Query.php

@@ -526,92 +526,88 @@ class Query extends Component implements QueryInterface
     {
         $this->where = $condition;
         $this->addParams($params);
-
         return $this;
     }
 
     /**
-     * Sets the WHERE part of the query ignoring empty parameters.
-     *
-     * @param string|array $condition the conditions that should be put in the WHERE part. Please refer to [[where()]]
+     * 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()]]
      * 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
-     * @see andFilter()
-     * @see orFilter()
+     * @see where()
+     * @see orWhere()
      */
-    public function filter($condition, $params = [])
+    public function andWhere($condition, $params = [])
     {
-        $condition = $this->filterCondition($condition);
-        if ($condition !== []) {
-            $this->where($condition, $params);
+        if ($this->where === null) {
+            $this->where = $condition;
+        } else {
+            $this->where = ['and', $this->where, $condition];
         }
+        $this->addParams($params);
 
         return $this;
     }
 
     /**
      * Adds an additional WHERE condition to the existing one.
-     * The new condition and the existing one will be joined using the 'AND' operator.
+     * The new condition and the existing one will be joined using the 'OR' operator.
      * @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
      * @see where()
-     * @see orWhere()
+     * @see andWhere()
      */
-    public function andWhere($condition, $params = [])
+    public function orWhere($condition, $params = [])
     {
         if ($this->where === null) {
             $this->where = $condition;
         } else {
-            $this->where = ['and', $this->where, $condition];
+            $this->where = ['or', $this->where, $condition];
         }
         $this->addParams($params);
-
         return $this;
     }
 
     /**
-     * Adds an additional WHERE condition to the existing one ignoring empty parameters.
-     * The new condition and the existing one will be joined using the 'AND' operator.
+     * Sets the WHERE part of the query ignoring empty parameters.
      *
-     * @param string|array $condition the new WHERE condition. Please refer to [[where()]]
+     * @param string|array $condition the conditions that should be put in the WHERE 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 static the query object itself
-     * @see filter()
+     * @see andFilter()
      * @see orFilter()
      */
-    public function andFilter($condition, $params = [])
+    public function filterWhere($condition, $params = [])
     {
         $condition = $this->filterCondition($condition);
         if ($condition !== []) {
-            $this->andWhere($condition, $params);
+            $this->where($condition, $params);
         }
-
         return $this;
     }
 
     /**
-     * Adds an additional WHERE condition to the existing one.
-     * The new condition and the existing one will be joined using the 'OR' operator.
+     * Adds an additional WHERE condition to the existing one ignoring empty parameters.
+     * 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()]]
      * 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
-     * @see where()
-     * @see andWhere()
+     * @see filter()
+     * @see orFilter()
      */
-    public function orWhere($condition, $params = [])
+    public function andFilterWhere($condition, $params = [])
     {
-        if ($this->where === null) {
-            $this->where = $condition;
-        } else {
-            $this->where = ['or', $this->where, $condition];
+        $condition = $this->filterCondition($condition);
+        if ($condition !== []) {
+            $this->andWhere($condition, $params);
         }
-        $this->addParams($params);
-
         return $this;
     }
 
@@ -626,13 +622,12 @@ class Query extends Component implements QueryInterface
      * @see filter()
      * @see andFilter()
      */
-    public function orFilter($condition, $params = [])
+    public function orFilterWhere($condition, $params = [])
     {
         $condition = $this->filterCondition($condition);
         if ($condition !== []) {
             $this->orWhere($condition, $params);
         }
-
         return $this;
     }
 
@@ -911,7 +906,7 @@ class Query extends Component implements QueryInterface
                 case 'OR':
                     for ($i = 1, $operandsCount = count($condition); $i < $operandsCount; $i++) {
                         $subCondition = $this->filterCondition($condition[$i]);
-                        if ($this->parameterNotEmpty($subCondition)) {
+                        if ($this->isParameterNotEmpty($subCondition)) {
                             $condition[$i] = $subCondition;
                         } else {
                             unset($condition[$i]);
@@ -935,13 +930,13 @@ class Query extends Component implements QueryInterface
                 case 'OR LIKE':
                 case 'NOT LIKE':
                 case 'OR NOT LIKE':
-                    if (!$this->parameterNotEmpty($condition[2])) {
+                    if (!$this->isParameterNotEmpty($condition[2])) {
                         $condition = [];
                     }
                 break;
                 case 'BETWEEN':
                 case 'NOT BETWEEN':
-                    if (!$this->parameterNotEmpty($condition[2]) && !$this->parameterNotEmpty($condition[3])) {
+                    if (!$this->isParameterNotEmpty($condition[2]) && !$this->isParameterNotEmpty($condition[3])) {
                         $condition = [];
                     }
                 break;

framework/db/QueryInterface.php

@@ -149,10 +149,10 @@ interface QueryInterface
      * @param array $condition the conditions that should be put in the WHERE part. Please refer to [[where()]]
      * on how to specify this parameter.
      * @return static the query object itself
-     * @see andFilter()
-     * @see orFilter()
+     * @see andFilterWhere()
+     * @see orFilterWhere()
      */
-    public function filter($condition);
+    public function filterWhere($condition);
 
     /**
      * Adds an additional WHERE condition to the existing one.
@@ -171,10 +171,10 @@ interface QueryInterface
      * @param string|array $condition the new WHERE condition. Please refer to [[where()]]
      * on how to specify this parameter.
      * @return static the query object itself
-     * @see filter()
-     * @see orFilter()
+     * @see filterWhere()
+     * @see orFilterWhere()
      */
-    public function andFilter($condition);
+    public function andFilterWhere($condition);
 
     /**
      * Adds an additional WHERE condition to the existing one.
@@ -193,10 +193,10 @@ interface QueryInterface
      * @param string|array $condition the new WHERE condition. Please refer to [[where()]]
      * on how to specify this parameter.
      * @return static the query object itself
-     * @see filter()
-     * @see andFilter()
+     * @see filterWhere()
+     * @see andFilterWhere()
      */
-    public function orFilter($condition);
+    public function orFilterWhere($condition);
 
     /**
      * Sets the ORDER BY part of the query.

framework/db/QueryTrait.php

@@ -6,6 +6,7 @@
  */
 
 namespace yii\db;
+use yii\base\NotSupportedException;
 
 /**
  * The BaseQuery trait represents the minimum method set of a database Query.
@@ -67,7 +68,6 @@ trait QueryTrait
     public function indexBy($column)
     {
         $this->indexBy = $column;
-
         return $this;
     }
 
@@ -84,149 +84,154 @@ trait QueryTrait
     public function where($condition)
     {
         $this->where = $condition;
-
         return $this;
     }
 
     /**
-     * Returns true if value passed is null, empty string, blank string, or empty array.
-     *
-     * @param $value
-     * @return boolean if parameter is empty
+     * 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()]]
+     * on how to specify this parameter.
+     * @return static the query object itself
+     * @see where()
+     * @see orWhere()
      */
-    protected function parameterNotEmpty($value)
-    {
-        if (is_string($value)) {
-            $value = trim($value);
-        }
-        return $value !== '' && $value !== [] && $value !== null;
-    }
-
-    /**
-    * Returns new condition with empty (null, empty string, blank string, or empty array) parameters in hash format
-    * removed
-    *
-    * @param array $condition original condition
-    * @return array condition with empty parameters removed
-    */
-    protected function filterHashCondition($condition)
+    public function andWhere($condition)
     {
-        if (is_array($condition) && !isset($condition[0])) {
-            // hash format: 'column1' => 'value1', 'column2' => 'value2', ...
-            $condition = array_filter($condition, [$this, 'parameterNotEmpty']);
+        if ($this->where === null) {
+            $this->where = $condition;
+        } else {
+            $this->where = ['and', $this->where, $condition];
         }
-        return $condition;
+        return $this;
     }
 
     /**
-     * Returns new condition with empty (null, empty string, blank string, or empty array) parameters removed
-     *
-     * @param array $condition original condition
-     * @return array condition with empty parameters removed
+     * Adds an additional WHERE condition to the existing one.
+     * The new condition and the existing one will be joined using the 'OR' operator.
+     * @param string|array $condition the new WHERE condition. Please refer to [[where()]]
+     * on how to specify this parameter.
+     * @return static the query object itself
+     * @see where()
+     * @see andWhere()
      */
-    protected function filterCondition($condition)
+    public function orWhere($condition)
     {
-        return $this->filterHashCondition($condition);
+        if ($this->where === null) {
+            $this->where = $condition;
+        } else {
+            $this->where = ['or', $this->where, $condition];
+        }
+        return $this;
     }
 
     /**
-     * Sets the WHERE part of the query ignoring empty parameters.
+     * Sets the WHERE part of the query but ignores [[isParameterNotEmpty|empty parameters]].
      *
-     * See [[QueryInterface::where()]] for detailed documentation.
+     * This function can be used to pass fields of a search form directly as search condition
+     * by ignoring fields that have not been filled.
      *
      * @param array $condition the conditions that should be put in the WHERE part.
+     * See [[where()]] on how to specify this parameter.
      * @return static the query object itself
-     * @see andFilter()
-     * @see orFilter()
+     * @see where()
+     * @see andFilterWhere()
+     * @see orFilterWhere()
      */
-    public function filter($condition)
+    public function filterWhere($condition)
     {
         $condition = $this->filterCondition($condition);
         if ($condition !== []) {
             $this->where($condition);
         }
-
         return $this;
     }
 
     /**
-     * Adds an additional WHERE condition to the existing one.
+     * Adds an additional WHERE condition to the existing one but ignores [[isParameterNotEmpty|empty parameters]].
      * 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()]]
      * on how to specify this parameter.
      * @return static the query object itself
-     * @see where()
-     * @see orWhere()
+     * @see filterWhere()
+     * @see orFilterWhere()
      */
-    public function andWhere($condition)
+    public function andFilterWhere($condition)
     {
-        if ($this->where === null) {
-            $this->where = $condition;
-        } else {
-            $this->where = ['and', $this->where, $condition];
+        $condition = $this->filterCondition($condition);
+        if ($condition !== []) {
+            $this->andWhere($condition);
         }
-
         return $this;
     }
 
     /**
-     * Adds an additional WHERE condition to the existing one ignoring empty parameters.
-     * The new condition and the existing one will be joined using the 'AND' operator.
-     *
+     * Adds an additional WHERE condition to the existing one but ignores [[isParameterNotEmpty|empty parameters]].
+     * The new condition and the existing one will be joined using the 'OR' operator.
      * @param string|array $condition the new WHERE condition. Please refer to [[where()]]
      * on how to specify this parameter.
      * @return static the query object itself
-     * @see filter()
-     * @see orFilter()
+     * @see filterWhere()
+     * @see andFilterWhere()
      */
-    public function andFilter($condition)
+    public function orFilterWhere($condition)
     {
         $condition = $this->filterCondition($condition);
         if ($condition !== []) {
-            $this->andWhere($condition);
+            $this->orWhere($condition);
         }
-
         return $this;
     }
 
     /**
-     * Adds an additional WHERE condition to the existing one.
-     * The new condition and the existing one will be joined using the 'OR' operator.
-     * @param string|array $condition the new WHERE condition. Please refer to [[where()]]
-     * on how to specify this parameter.
-     * @return static the query object itself
-     * @see where()
-     * @see andWhere()
+     * Returns a new condition with [[isParameterNotEmpty|empty parameters]] removed.
+     *
+     * @param array $condition original condition
+     * @return array condition with [[isParameterNotEmpty|empty parameters]] removed.
      */
-    public function orWhere($condition)
+    protected function filterCondition($condition)
     {
-        if ($this->where === null) {
-            $this->where = $condition;
+        if (is_array($condition) && !isset($condition[0])) {
+            return $this->filterHashCondition($condition);
         } else {
-            $this->where = ['or', $this->where, $condition];
+            throw new NotSupportedException('filterWhere() only supports hash condition format.');
         }
-
-        return $this;
     }
 
     /**
-     * Adds an additional WHERE condition to the existing one ignoring empty parameters.
-     * The new condition and the existing one will be joined using the 'OR' operator.
+     * Returns `true` if value passed is not "empty".
      *
-     * @param string|array $condition the new WHERE condition. Please refer to [[where()]]
-     * on how to specify this parameter.
-     * @return static the query object itself
-     * @see filter()
-     * @see andFilter()
+     * The value is considered "empty", if
+     *
+     * - it is `null`,
+     * - an empty string (`''`),
+     * - a string containing only whitespace characters,
+     * - or an empty array.
+     *
+     * @param $value
+     * @return boolean if parameter is empty
      */
-    public function orFilter($condition)
+    protected function isParameterNotEmpty($value)
     {
-        $condition = $this->filterCondition($condition);
-        if ($condition !== []) {
-            $this->orWhere($condition);
+        if (is_string($value)) {
+            $value = trim($value);
         }
+        return $value !== '' && $value !== [] && $value !== null;
+    }
 
-        return $this;
+    /**
+     * Returns a new hash condition without [[isParameterNotEmpty|empty parameters]].
+     *
+     * @param array $condition original condition
+     * @return array condition without [[isParameterNotEmpty|empty parameters]].
+     */
+    protected function filterHashCondition($condition)
+    {
+        if (is_array($condition) && !isset($condition[0])) {
+            // hash format: 'column1' => 'value1', 'column2' => 'value2', ...
+            return array_filter($condition, [$this, 'isParameterNotEmpty']);
+        }
+        return $condition;
     }
 
     /**
@@ -245,7 +250,6 @@ trait QueryTrait
     public function orderBy($columns)
     {
         $this->orderBy = $this->normalizeOrderBy($columns);
-
         return $this;
     }
 
@@ -267,7 +271,6 @@ trait QueryTrait
         } else {
             $this->orderBy = array_merge($this->orderBy, $columns);
         }
-
         return $this;
     }
 
@@ -285,7 +288,6 @@ trait QueryTrait
                     $result[$column] = SORT_ASC;
                 }
             }
-
             return $result;
         }
     }
@@ -298,7 +300,6 @@ trait QueryTrait
     public function limit($limit)
     {
         $this->limit = $limit;
-
         return $this;
     }
 
@@ -310,7 +311,6 @@ trait QueryTrait
     public function offset($offset)
     {
         $this->offset = $offset;
-
         return $this;
     }
 }

tests/unit/extensions/elasticsearch/QueryTest.php

@@ -155,7 +155,7 @@ class QueryTest extends ElasticSearchTestCase
     {
         // should work with hash format
         $query = new Query;
-        $query->filter([
+        $query->filterWhere([
             'id' => 0,
             'title' => '   ',
             'author_ids' => [],

tests/unit/extensions/mongodb/QueryTest.php

@@ -72,7 +72,7 @@ class QueryTest extends MongoDbTestCase
     {
         // should work with hash format
         $query = new Query;
-        $query->filter([
+        $query->filterWhere([
             'id' => 0,
             'title' => '   ',
             'author_ids' => [],

tests/unit/extensions/sphinx/QueryTest.php

@@ -64,13 +64,13 @@ class QueryTest extends SphinxTestCase
     {
         // should just call where() when string is passed
         $query = new Query;
-        $query->filter('id = :id', [':id' => null]);
+        $query->filterWhere('id = :id', [':id' => null]);
         $this->assertEquals('id = :id', $query->where);
         $this->assertEquals([':id' => null], $query->params);
 
         // should work with hash format
         $query = new Query;
-        $query->filter([
+        $query->filterWhere([
             'id' => 0,
             'title' => '   ',
             'author_ids' => [],
@@ -86,7 +86,7 @@ class QueryTest extends SphinxTestCase
         // should work with operator format
         $query = new Query;
         $condition = ['like', 'name', 'Alex'];
-        $query->filter($condition);
+        $query->filterWhere($condition);
         $this->assertEquals($condition, $query->where);
 
         $query->andFilter(['between', 'id', null, null]);
@@ -120,7 +120,7 @@ class QueryTest extends SphinxTestCase
     public function testFilterRecursively()
     {
         $query = new Query();
-        $query->filter(['and', ['like', 'name', ''], ['like', 'title', ''], ['id' => 1], ['not', ['like', 'name', '']]]);
+        $query->filterWhere(['and', ['like', 'name', ''], ['like', 'title', ''], ['id' => 1], ['not', ['like', 'name', '']]]);
         $this->assertEquals(['id' => 1], $query->where);
     }
 

tests/unit/framework/db/QueryTest.php

@@ -53,13 +53,13 @@ class QueryTest extends DatabaseTestCase
     {
         // should just call where() when string is passed
         $query = new Query;
-        $query->filter('id = :id', [':id' => null]);
+        $query->filterWhere('id = :id', [':id' => null]);
         $this->assertEquals('id = :id', $query->where);
         $this->assertEquals([':id' => null], $query->params);
 
         // should work with hash format
         $query = new Query;
-        $query->filter([
+        $query->filterWhere([
             'id' => 0,
             'title' => '   ',
             'author_ids' => [],
@@ -75,7 +75,7 @@ class QueryTest extends DatabaseTestCase
         // should work with operator format
         $query = new Query;
         $condition = ['like', 'name', 'Alex'];
-        $query->filter($condition);
+        $query->filterWhere($condition);
         $this->assertEquals($condition, $query->where);
 
         $query->andFilter(['between', 'id', null, null]);
@@ -109,7 +109,7 @@ class QueryTest extends DatabaseTestCase
     public function testFilterRecursively()
     {
         $query = new Query();
-        $query->filter(['and', ['like', 'name', ''], ['like', 'title', ''], ['id' => 1], ['not', ['like', 'name', '']]]);
+        $query->filterWhere(['and', ['like', 'name', ''], ['like', 'title', ''], ['id' => 1], ['not', ['like', 'name', '']]]);
         $this->assertEquals(['id' => 1], $query->where);
     }