+ update methods name refactoring as suggested in PR #2343 (exprOr to aggregationExpression and createExpr to createQueryExpression and createAggregationExpression)

+ add depreciation triggers
+ refactoring associated tests
- remove unnecessary exprOp in Aggregation\Expr

Author: Vincent Le Henaff

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

@@ -163,7 +163,7 @@ public function count(string $fieldName): Stage\Count
     /**
      * Create a new Expr instance that can be used as an expression with the Builder
      */
-    public function createExpr(): Expr
+    public function createAggregationExpression(): Expr
     {
         return new Expr($this->dm, $this->class);
     }
@@ -193,7 +193,15 @@ public function execute(array $options = []): Iterator
      */
     public function expr(): Expr
     {
-        return $this->createExpr();
+        trigger_deprecation(
+            'doctrine/mongodb-odm',
+            '2.3',
+            'The "%s" method is deprecated. Please use "%s::createAggregationExpression" instead.',
+            __METHOD__,
+            static::class
+        );
+
+        return $this->createAggregationExpression();
     }
 
     /**

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

@@ -326,8 +326,10 @@ public static function convertExpression($expression)
 
     /**
      * Returns a new expression object
+     *
+     * @return static
      */
-    public function createExpr(): self
+    public function createAggregationExpression(): self
     {
         return new static($this->dm, $this->class);
     }
@@ -466,20 +468,15 @@ public function exp($exponent): self
      */
     public function expr(): self
     {
-        return $this->createExpr();
-    }
+        trigger_deprecation(
+            'doctrine/mongodb-odm',
+            '2.3',
+            'The "%s" method is deprecated. Please use "%s::createAggregationExpression" instead.',
+            __METHOD__,
+            static::class
+        );
 
-    /**
-     * Specify $expr criteria for the current field.
-     *
-     * @see Builder::expr()
-     * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
-     *
-     * @param array|self $expression
-     */
-    public function exprOp($expression): self
-    {
-        return $this->operator('$expr', $expression);
+        return $this->createAggregationExpression();
     }
 
     /**

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

@@ -4,6 +4,7 @@
 
 namespace Doctrine\ODM\MongoDB\Aggregation\Stage;
 
+use Doctrine\ODM\MongoDB\Aggregation;
 use Doctrine\ODM\MongoDB\Aggregation\Builder;
 use Doctrine\ODM\MongoDB\Aggregation\Stage;
 use Doctrine\ODM\MongoDB\Query\Expr;
@@ -118,7 +119,7 @@ public function all(array $values): self
      * Create a new Expr instance that can be used to build partial expressions
      * for other operator methods.
      */
-    public function createExpr(): Expr
+    public function createQueryExpression(): Expr
     {
         return $this->builder->matchExpr();
     }
@@ -179,20 +180,28 @@ public function exists(bool $bool): self
      */
     public function expr(): Expr
     {
-        return $this->createExpr();
+        trigger_deprecation(
+            'doctrine/mongodb-odm',
+            '2.3',
+            'The "%s" method is deprecated. Please use "%s::createQueryExpression" instead.',
+            __METHOD__,
+            static::class
+        );
+
+        return $this->createQueryExpression();
     }
 
     /**
      * Specify $expr criteria for the current field.
      *
-     * @see Expr::exprOp()
+     * @param array|Aggregation\Expr $expression
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
      *
-     * @param array|\Doctrine\ODM\MongoDB\Aggregation\Expr $expression
+     * @see Expr::aggregationExpression()
      */
-    public function exprOp($expression): self
+    public function aggregationExpression($expression): self
     {
-        $this->query->exprOp($expression);
+        $this->query->aggregationExpression($expression);
 
         return $this;
     }

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

@@ -5,6 +5,7 @@
 namespace Doctrine\ODM\MongoDB\Query;
 
 use BadMethodCallException;
+use Doctrine\ODM\MongoDB\Aggregation;
 use Doctrine\ODM\MongoDB\DocumentManager;
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use GeoJson\Geometry\Geometry;
@@ -359,7 +360,7 @@ public function count(): self
     /**
      * Create a new Expr instance that can be used as an expression with the Builder
      */
-    public function createExpr(): Expr
+    public function createQueryExpression(): Expr
     {
         $expr = new Expr($this->dm);
         $expr->setClassMetadata($this->class);
@@ -499,20 +500,28 @@ public function exists(bool $bool): self
      */
     public function expr(): Expr
     {
-        return $this->createExpr();
+        trigger_deprecation(
+            'doctrine/mongodb-odm',
+            '2.3',
+            'The "%s" method is deprecated. Please use "%s::createQueryExpression" instead.',
+            __METHOD__,
+            static::class
+        );
+
+        return $this->createQueryExpression();
     }
 
     /**
      * Specify $expr criteria for the current field.
      *
-     * @see Expr::exprOp()
+     * @param array|Aggregation\Expr $expression
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
      *
-     * @param array|Expr $expression
+     * @see Aggregation\Expr::aggregationExpression()
      */
-    public function exprOp($expression): self
+    public function aggregationExpression($expression): self
     {
-        $this->expr->exprOp($expression);
+        $this->expr->aggregationExpression($expression);
 
         return $this;
     }

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

@@ -5,6 +5,7 @@
 namespace Doctrine\ODM\MongoDB\Query;
 
 use BadMethodCallException;
+use Doctrine\ODM\MongoDB\Aggregation;
 use Doctrine\ODM\MongoDB\DocumentManager;
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\Mapping\MappingException;
@@ -407,12 +408,12 @@ public function elemMatch($expression): self
     /**
      * Specify $expr criteria for the current field.
      *
-     * @see Builder::exprOp()
+     * @see Builder::aggregationExpression()
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
      *
-     * @param array|Expr $expression
+     * @param array|Aggregation\Expr $expression
      */
-    public function exprOp($expression): self
+    public function aggregationExpression($expression): self
     {
         return $this->operator('$expr', $expression);
     }

tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php

@@ -192,9 +192,9 @@ public static function provideExpressionOperators(): array
                 'operator' => 'exp',
                 'args' => ['$field'],
             ],
-            'exprOp' => [
+            'aggregationExpression' => [
                 'expected' => ['$expr' => ['$eq' => ['$field', '$otherField']]],
-                'operator' => 'exprOp',
+                'operator' => 'aggregationExpression',
                 'args' => [['$eq' => ['$field', '$otherField']]],
             ],
             'filter' => [