[FRAM-87] Replace a where clause (#67)

* feat: Replace a where clause (#FRAM-87)

* fix: Where replace with null value

* chore: Update changelog for #FRAM-87

CHANGELOG

@@ -19,6 +19,7 @@ v2.1.0
 * Change: `Clause::buildClause()`, and all related methods like `Wherable::where()` now handle iterable expression parameters.
   This change allows to use the `Criteria` as parameter of the where clause without the need to call `Criteria::all()`
 * Feat: Add `Bdf\Prime\Query\Expression\Operator` to wrap the operator and the value as expression. So it can be used in on criteria setters
+* Feat: Add `Clause::replaceClause()` and `Wherable::replaceWhere()` to replace a single filter value. Method `Wherable::replaceWhere()` is commented for now to avoid BC break.
 
 v2.0.6
 ------

src/Query/Clause.php

@@ -172,6 +172,42 @@ public function buildClause(string $statement, $expression, $operator = null, $v
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function replaceClause(string $statement, string $expression, $operator = null, $value = null)
+    {
+        if ($value === null && (!is_string($operator) || !isset($this->operators[$operator]))) {
+            $value = $operator;
+            $operator = '=';
+        }
+
+        $found = false;
+
+        foreach ($this->statements[$statement] ?? [] as $key => $clause) {
+            if (
+                isset($clause['column'], $clause['operator'])
+                && $clause['column'] === $expression
+                && $clause['operator'] === $operator
+            ) {
+                $this->statements[$statement][$key]['value'] = $value;
+                $found = true;
+                break;
+            }
+        }
+
+        if (!$found) {
+            $this->statements[$statement][] = [
+                'column'    => $expression,
+                'operator'  => $operator,
+                'value'     => $value,
+                'glue'      => CompositeExpression::TYPE_AND,
+            ];
+        }
+
+        return $this;
+    }
+
     /**
      * {@inheritdoc}
      */

src/Query/ClauseInterface.php

@@ -91,6 +91,29 @@ public function addStatement(string $name, $values): void;
      */
     public function buildClause(string $statement, $expression, $operator = null, $value = null, string $type = CompositeExpression::TYPE_AND);
 
+    /**
+     * Replace a clause value
+     *
+     * If the clause does not exist, it will be added
+     * Only the first statement matching the expression and the operator will be replaced
+     *
+     * Note: unlike the buildClause method, this method does not support the array syntax nor nested statements
+     *
+     * <code>
+     *   $query->from('users', 'u')->where('u.id', '=', 1); // SELECT * FROM users u WHERE u.id = 1
+     *   $query->replaceClause('where', 'u.id', '=', 2); // Replace the clause : SELECT * FROM users u WHERE u.id = 2
+     *   $query->replaceClause('where', 'u.id', '<', 1000); // Operator is different, so the clause is added : SELECT * FROM users u WHERE u.id = 2 AND u.id < 1000
+     * </code>
+     *
+     * @param string $statement Statement name to modify. e.g. where, having, on...
+     * @param string $expression Column name or expression
+     * @param string|mixed|null $operator Comparison operator. If the $value parameter is omitted, this parameter is used as the value, and the operator is set to '='.
+     * @param mixed $value The value to compare to.
+     *
+     * @return $this
+     */
+    public function replaceClause(string $statement, string $expression, $operator = null, $value = null);
+
     /**
      * Add a raw expression in statement
      *

src/Query/Contract/Whereable.php

@@ -6,12 +6,13 @@
 
 /**
  * Interface for where() method
+ *
+ * @method $this whereReplace(string $column, $operator = null, $value = null) Add or replace single where criterion.
  */
 interface Whereable
 {
     /**
      * Specifies one or more restrictions to the query result.
-     * Replaces any previously specified restrictions, if any.
      *
      * <code>
      *     $query
@@ -37,6 +38,31 @@ interface Whereable
      */
     public function where($column, $operator = null, $value = null);
 
+    /**
+     * Add or replace single where criterion
+     * The criterion value will be replaced on the first occurrence matching with the column and the operator
+     *
+     * Note: Unlike the where() method, this method does not support the array syntax nor nested statements
+     *
+     * <code>
+     *     $query
+     *         ->select('u.name')
+     *         ->from('users', 'u')
+     *         ->whereReplace('u.id', '1') // Filter not existing, will be added
+     *     ;
+     *
+     *     $query->whereReplace('u.id', '2'); // Will replace the previous where
+     *     $query->whereReplace('u.id', '<', '1000'); // Operator is different, so the clause is added
+     * </code>
+     *
+     * @param string $column The column name to filter
+     * @param string|mixed|null $operator The comparison operator, or the value is you want to use "=" operator
+     * @param mixed $value
+     *
+     * @return $this This Query instance.
+     */
+    //public function whereReplace(string $column, $operator = null, $value = null); // @todo uncomment on prime 3.0
+
     /**
      * Adds one or more restrictions to the query results, forming a logical
      * disjunction with any previously specified restrictions.

src/Query/Extension/SimpleWhereTrait.php

@@ -35,6 +35,18 @@ public function where($column, $operator = null, $value = null)
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * @see Whereable::whereReplace()
+     */
+    public function whereReplace(string $column, $operator = null, $value = null)
+    {
+        $this->compilerState->invalidate('where');
+        $this->replaceClause('where', $column, $operator, $value);
+        return $this;
+    }
+
     /**
      * {@inheritdoc}
      *
@@ -138,6 +150,13 @@ public function nested(callable $callback, string $type = CompositeExpression::T
      */
     abstract public function buildClause(string $statement, $expression, $operator = null, $value = null, string $type = CompositeExpression::TYPE_AND);
 
+    /**
+     * {@inheritdoc}
+     *
+     * @see Clause::replaceClause()
+     */
+    abstract public function replaceClause(string $statement, string $expression, $operator = null, $value = null);
+
     /**
      * {@inheritdoc}
      *

src/Query/Pagination/WalkStrategy/KeyWalkStrategy.php

@@ -13,6 +13,8 @@
 use Bdf\Prime\Query\ReadCommandInterface;
 use InvalidArgumentException;
 
+use function method_exists;
+
 /**
  * Walk strategy using a primary key (or any unique key) as cursor
  * This strategy supports deleting entities during the walk, but the entity must contains a single primary key, and the query must be ordered by this key
@@ -78,25 +80,11 @@ public function next(WalkCursor $cursor): WalkCursor
             $column = $this->key->name();
             $operator = $query->getOrders()[$column] === Orderable::ORDER_ASC ? '>' : '<';
 
-            // Quick fix for FRAM-86 : reset where clause
-            $set = false;
-
-            if ($query instanceof CompilableClause && !empty($query->statements['where'])) {
-                foreach ($query->statements['where'] as $key => $statement) {
-                    if (
-                        isset($statement['column'], $statement['operator'], $statement['value'])
-                        && $statement['column'] === $column
-                        && $statement['operator'] === $operator
-                    ) {
-                        $query->statements['where'][$key]['value'] = $cursor->cursor;
-                        $set = true;
-                        $query->state()->invalidate('where');
-                        break;
-                    }
-                }
-            }
-
-            if (!$set) {
+            // #FRAM-86 : reset where clause
+            // @todo remove method_exists check on prime 3.0
+            if (method_exists($query, 'whereReplace')) {
+                $query->whereReplace($column, $operator, $cursor->cursor);
+            } else {
                 $query->where($column, $operator, $cursor->cursor);
             }
         }

tests/Query/QueryTest.php

@@ -1610,4 +1610,22 @@ public function test_count_alias()
             $query->toSql()
         );
     }
+
+    public function test_whereReplace()
+    {
+        $query = $this->query()->whereReplace('id', 1);
+
+        $this->assertEquals('SELECT * FROM test_ WHERE id = 1', $query->toRawSql());
+        $this->assertEquals('SELECT * FROM test_ WHERE id = 3', $query->whereReplace('id', 3)->toRawSql());
+        $this->assertEquals('SELECT * FROM test_ WHERE id = 3 AND id < 42', $query->whereReplace('id', '<', 42)->toRawSql());
+        $this->assertEquals('SELECT * FROM test_ WHERE id = 3 AND id < 42 AND raw clause', $query->whereRaw('raw clause')->toRawSql());
+    }
+
+    public function test_whereReplace_null()
+    {
+        $query = $this->query()->whereReplace('id', null);
+
+        $this->assertEquals('SELECT * FROM test_ WHERE id IS NULL', $query->toRawSql());
+        $this->assertEquals('SELECT * FROM test_ WHERE id = 42', $query->whereReplace('id', 42)->toRawSql());
+    }
 }