Support expr in queries

composer.json

@@ -22,7 +22,7 @@
         { "name": "Andreas Braun", "email": "[email protected]" }
     ],
     "require": {
-        "php": "^7.4 || ^8.0",
+        "php": "^8.1",
         "ext-mongodb": "^1.5",
         "doctrine/annotations": "^1.12",
         "doctrine/cache": "^1.11 || ^2.0",

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 createAggregationExpression(): Expr
+    {
+        return new Expr($this->dm, $this->class);
+    }
+
     /**
      * Executes the aggregation pipeline
      *
@@ -180,9 +188,20 @@ public function execute(array $options = []): Iterator
         return $this->getAggregation($options)->getIterator();
     }
 
+    /**
+     * @deprecated use createAggregationExpression instead
+     */
     public function expr(): Expr
     {
-        return new Expr($this->dm, $this->class);
+        trigger_deprecation(
+            'doctrine/mongodb-odm',
+            '2.5',
+            'The "%s" method is deprecated. Please use "%s::createAggregationExpression" instead.',
+            __METHOD__,
+            static::class
+        );
+
+        return $this->createAggregationExpression();
     }
 
     /**

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

@@ -19,6 +19,7 @@
 use function is_array;
 use function is_string;
 use function substr;
+use function trigger_deprecation;
 
 /**
  * Fluent interface for building aggregation pipelines.
@@ -324,6 +325,16 @@ public static function convertExpression($expression)
         return $expression;
     }
 
+    /**
+     * Returns a new expression object
+     *
+     * @return static
+     */
+    public function createAggregationExpression(): self
+    {
+        return new static($this->dm, $this->class);
+    }
+
     /**
      * Converts a date object to a string according to a user-specified format.
      *
@@ -453,10 +464,20 @@ public function exp($exponent): self
 
     /**
      * Returns a new expression object
+     *
+     * @deprecated use createAggregationExpression instead
      */
     public function expr(): self
     {
-        return new static($this->dm, $this->class);
+        trigger_deprecation(
+            'doctrine/mongodb-odm',
+            '2.5',
+            'The "%s" method is deprecated. Please use "%s::createAggregationExpression" instead.',
+            __METHOD__,
+            static::class
+        );
+
+        return $this->createAggregationExpression();
     }
 
     /**

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

@@ -4,12 +4,14 @@
 
 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;
 use GeoJson\Geometry\Geometry;
 
 use function func_get_args;
+use function trigger_deprecation;
 
 /**
  * Fluent interface for building aggregation pipelines.
@@ -114,6 +116,15 @@ public function all(array $values): self
         return $this;
     }
 
+    /**
+     * Create a new Expr instance that can be used to build partial expressions
+     * for other operator methods.
+     */
+    public function createQueryExpression(): Expr
+    {
+        return $this->builder->matchExpr();
+    }
+
     /**
      * Specify $elemMatch criteria for the current field.
      *
@@ -166,12 +177,34 @@ public function exists(bool $bool): self
     }
 
     /**
-     * Create a new Expr instance that can be used to build partial expressions
-     * for other operator methods.
+     * @deprecated use createExpr instead
      */
     public function expr(): Expr
     {
-        return $this->builder->matchExpr();
+        trigger_deprecation(
+            'doctrine/mongodb-odm',
+            '2.5',
+            'The "%s" method is deprecated. Please use "%s::createQueryExpression" instead.',
+            __METHOD__,
+            static::class
+        );
+
+        return $this->createQueryExpression();
+    }
+
+    /**
+     * Specify $expr criteria for the current field.
+     *
+     * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     * @see Expr::aggregationExpression()
+     *
+     * @param array|Aggregation\Expr $expression
+     */
+    public function aggregationExpression($expression): self
+    {
+        $this->query->aggregationExpression($expression);
+
+        return $this;
     }
 
     /**

lib/Doctrine/ODM/MongoDB/DocumentManager.php

@@ -284,7 +284,6 @@ public function getClassNameResolver(): ClassNameResolver
      * @psalm-return ClassMetadata<T>
      *
      * @template T of object
-     *
      * @psalm-suppress InvalidReturnType, InvalidReturnStatement see https://github.com/vimeo/psalm/issues/5788
      */
     public function getClassMetadata($className): ClassMetadata

lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php

@@ -6,9 +6,9 @@
 
 use Countable;
 use Generator;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
+use ReturnTypeWillChange;
 
 use function count;
 use function current;

lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php

@@ -8,9 +8,9 @@
 use Doctrine\ODM\MongoDB\UnitOfWork;
 use Generator;
 use Iterator;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
+use ReturnTypeWillChange;
 
 /**
  * Iterator that wraps a traversable and hydrates results into objects

lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php

@@ -6,9 +6,9 @@
 
 use Generator;
 use LogicException;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
+use ReturnTypeWillChange;
 
 use function iterator_to_array;
 use function sprintf;

lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php

@@ -12,8 +12,8 @@
 use Doctrine\ODM\MongoDB\MongoDBException;
 use Doctrine\ODM\MongoDB\UnitOfWork;
 use Doctrine\ODM\MongoDB\Utility\CollectionHelper;
-use ReturnTypeWillChange;
 use Traversable;
+use ReturnTypeWillChange;
 
 use function array_combine;
 use function array_diff_key;

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;
@@ -25,6 +26,7 @@
 use function is_callable;
 use function is_string;
 use function strtolower;
+use function trigger_deprecation;
 
 /**
  * Query builder for ODM.
@@ -356,6 +358,17 @@ public function count(): self
         return $this;
     }
 
+    /**
+     * Create a new Expr instance that can be used as an expression with the Builder
+     */
+    public function createQueryExpression(): 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 +496,35 @@ public function exists(bool $bool): self
 
     /**
      * Create a new Expr instance that can be used as an expression with the Builder
+     *
+     * @deprecated use createQueryExpression instead
      */
     public function expr(): Expr
     {
-        $expr = new Expr($this->dm);
-        $expr->setClassMetadata($this->class);
+        trigger_deprecation(
+            'doctrine/mongodb-odm',
+            '2.5',
+            'The "%s" method is deprecated. Please use "%s::createQueryExpression" instead.',
+            __METHOD__,
+            static::class
+        );
 
-        return $expr;
+        return $this->createQueryExpression();
+    }
+
+    /**
+     * Specify $expr criteria for the current field.
+     *
+     * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     * @see Aggregation\Expr::aggregationExpression()
+     *
+     * @param array|Aggregation\Expr $expression
+     */
+    public function aggregationExpression($expression): self
+    {
+        $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;
@@ -404,6 +405,19 @@ public function elemMatch($expression): self
         return $this->operator('$elemMatch', $expression);
     }
 
+    /**
+     * Specify $expr criteria for the current field.
+     *
+     * @see Builder::aggregationExpression()
+     * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     *
+     * @param array|Aggregation\Expr $expression
+     */
+    public function aggregationExpression($expression): self
+    {
+        return $this->operator('$expr', $expression);
+    }
+
     /**
      * Specify an equality match for the current field.
      *

lib/Doctrine/ODM/MongoDB/UnitOfWork.php

@@ -55,7 +55,7 @@
  *      1: mixed
  * }
  * @psalm-type Hints = array<int, mixed>
- * @psalm-type CommitOptions array{
+ * @psalm-type CommitOptions = array{
  *      fsync?: bool,
  *      safe?: int,
  *      w?: int,
@@ -1601,7 +1601,6 @@ public function removeFromIdentityMap(object $document): bool
      * @throws InvalidArgumentException If the class does not have an identifier.
      *
      * @template T of object
-     *
      * @psalm-suppress InvalidReturnStatement, InvalidReturnType because of the inability of defining a generic property map
      */
     public function getById($id, ClassMetadata $class): object
@@ -1630,7 +1629,6 @@ public function getById($id, ClassMetadata $class): object
      * @throws InvalidArgumentException If the class does not have an identifier.
      *
      * @template T of object
-     *
      * @psalm-suppress InvalidReturnStatement, InvalidReturnType because of the inability of defining a generic property map
      */
     public function tryGetById($id, ClassMetadata $class)