+ implement $expr operator as exprOp method for query and aggregation builders

+ add createExpr and depreciation notice for Builder::expr for further revision of exprOp method naming to expr

Author: Vincent Le Henaff

lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php

@@ -160,6 +160,14 @@ public function count(string $fieldName): Stage\Count
         return $stage;
     }
 
+    /**
+     * Create a new Expr instance that can be used as an expression with the Builder
+     */
+    public function createExpr(): Expr
+    {
+        return new Expr($this->dm, $this->class);
+    }
+
     /**
      * Executes the aggregation pipeline
      *
@@ -180,9 +188,14 @@ public function execute(array $options = []): Iterator
         return $this->getAggregation($options)->getIterator();
     }
 
+    /**
+     * @return Expr
+     *
+     * @deprecated use createExpr instead
+     */
     public function expr(): Expr
     {
-        return new Expr($this->dm, $this->class);
+        return $this->createExpr();
     }
 
     /**

lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php

@@ -324,6 +324,14 @@ public static function convertExpression($expression)
         return $expression;
     }
 
+    /**
+     * Returns a new expression object
+     */
+    public function createExpr(): self
+    {
+        return new static($this->dm, $this->class);
+    }
+
     /**
      * Converts a date object to a string according to a user-specified format.
      *
@@ -453,10 +461,25 @@ public function exp($exponent): self
 
     /**
      * Returns a new expression object
+     *
+     * @deprecated use createExpr instead
      */
     public function expr(): self
     {
-        return new static($this->dm, $this->class);
+        return $this->createExpr();
+    }
+
+    /**
+     * Specify $expr criteria for the current field.
+     *
+     * @see Builder::expr()
+     * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     *
+     * @param array|\Doctrine\ODM\MongoDB\Query\Expr $expression
+     */
+    public function exprOp($expression): self
+    {
+        return $this->operator('$expr', $expression);
     }
 
     /**

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php

@@ -114,6 +114,24 @@ public function all(array $values): self
         return $this;
     }
 
+    /**
+     * Specify $expr criteria for the current field.
+     *
+     * You can create a new expression using the {@link Builder::matchExpr()}
+     * method.
+     *
+     * @see Expr::expr()
+     * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     *
+     * @param array|Expr $expression
+     */
+    public function createExpr($expression): self
+    {
+        $this->query->expr($expression);
+
+        return $this;
+    }
+
     /**
      * Specify $elemMatch criteria for the current field.
      *
@@ -166,12 +184,34 @@ public function exists(bool $bool): self
     }
 
     /**
-     * Create a new Expr instance that can be used to build partial expressions
-     * for other operator methods.
+     * Specify $expr criteria for the current field.
+     *
+     * You can create a new expression using the {@link Builder::matchExpr()}
+     * method.
+     *
+     * @see Expr::expr()
+     * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     *
+     * @param array|Expr $expression
+     *
+     * @deprecated use createExpr instead
+     */
+    public function expr($expression): self
+    {
+        return $this->createExpr($expression);
+    }
+
+    /**
+     * Specify $expr criteria for the current field.
+     *
+     * @see Expr::exprOp()
+     * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
      */
-    public function expr(): Expr
+    public function exprOp($expression): self
     {
-        return $this->builder->matchExpr();
+        $this->query->exprOp($expression);
+
+        return $this;
     }
 
     /**

lib/Doctrine/ODM/MongoDB/Query/Builder.php

@@ -356,6 +356,17 @@ public function count(): self
         return $this;
     }
 
+    /**
+     * Create a new Expr instance that can be used as an expression with the Builder
+     */
+    public function createExpr(): Expr
+    {
+        $expr = new Expr($this->dm);
+        $expr->setClassMetadata($this->class);
+
+        return $expr;
+    }
+
     /**
      * Sets the value of the current field to the current date, either as a date or a timestamp.
      *
@@ -483,13 +494,25 @@ public function exists(bool $bool): self
 
     /**
      * Create a new Expr instance that can be used as an expression with the Builder
+     *
+     * @deprecated use createExpr instead
      */
     public function expr(): Expr
     {
-        $expr = new Expr($this->dm);
-        $expr->setClassMetadata($this->class);
+        return $this->createExpr();
+    }
 
-        return $expr;
+    /**
+     * Specify $expr criteria for the current field.
+     *
+     * @see Expr::exprOp()
+     * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     */
+    public function exprOp($expression): self
+    {
+        $this->expr->exprOp($expression);
+
+        return $this;
     }
 
     /**

lib/Doctrine/ODM/MongoDB/Query/Expr.php

@@ -404,6 +404,19 @@ public function elemMatch($expression): self
         return $this->operator('$elemMatch', $expression);
     }
 
+    /**
+     * Specify $expr criteria for the current field.
+     *
+     * @see Builder::exprOp()
+     * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     *
+     * @param array|Expr $expression
+     */
+    public function exprOp($expression): self
+    {
+        return $this->operator('$expr', $expression);
+    }
+
     /**
      * Specify an equality match for the current field.
      *