From 5264e26144d7fd8640a05dc09819c881a93a6bd4 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sat, 17 Jul 2021 21:41:31 +0200
Subject: [PATCH 01/31] + 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

---
 .../ODM/MongoDB/Aggregation/Builder.php       | 15 +++++-
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php | 25 +++++++++-
 .../MongoDB/Aggregation/Stage/MatchStage.php  | 48 +++++++++++++++++--
 lib/Doctrine/ODM/MongoDB/Query/Builder.php    | 29 +++++++++--
 lib/Doctrine/ODM/MongoDB/Query/Expr.php       | 13 +++++
 5 files changed, 121 insertions(+), 9 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
index 39c27ba740..a0ab22a48f 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
@@ -162,6 +162,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();
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index 1d8e9fe2bd..fa077c02dc 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
@@ -333,6 +333,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.
      *
@@ -462,10 +470,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);
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index 97c03de2d6..24ab7b73b9 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -107,6 +107,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.
      *
@@ -153,12 +171,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;
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index 2c959178ce..9caabb50c3 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
@@ -366,6 +366,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.
      *
@@ -493,13 +504,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;
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Expr.php b/lib/Doctrine/ODM/MongoDB/Query/Expr.php
index 86e47f4dfd..5904c71e3e 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Expr.php
+++ b/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.
      *

From 4725c1958e9e3f3a8d82b20893d618ccc82cf9e2 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sat, 17 Jul 2021 22:02:01 +0200
Subject: [PATCH 02/31] * fix MatchStage expr revision introduced bug

---
 .../ODM/MongoDB/Aggregation/Builder.php       |  2 --
 .../MongoDB/Aggregation/Stage/MatchStage.php  | 31 ++++---------------
 2 files changed, 6 insertions(+), 27 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
index a0ab22a48f..8c78867e3b 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
@@ -189,8 +189,6 @@ public function execute(array $options = []): Iterator
     }
 
     /**
-     * @return Expr
-     *
      * @deprecated use createExpr instead
      */
     public function expr(): Expr
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index 24ab7b73b9..a147689e9c 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -108,21 +108,12 @@ public function all(array $values): self
     }
 
     /**
-     * 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
+     * Create a new Expr instance that can be used to build partial expressions
+     * for other operator methods.
      */
-    public function createExpr($expression): self
+    public function createExpr(): Expr
     {
-        $this->query->expr($expression);
-
-        return $this;
+        return $this->builder->matchExpr();
     }
 
     /**
@@ -171,21 +162,11 @@ public function exists(bool $bool): self
     }
 
     /**
-     * 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
+    public function expr(): Expr
     {
-        return $this->createExpr($expression);
+        return $this->createExpr();
     }
 
     /**

From 0a38fa571f8226df95ef40072c77adeaad79359e Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sun, 18 Jul 2021 02:07:37 +0200
Subject: [PATCH 03/31] + add exprOp test + add contextual missing type hint
 for exprOr

---
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php                | 2 +-
 lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php    | 2 ++
 lib/Doctrine/ODM/MongoDB/Query/Builder.php                   | 2 ++
 .../Tests/Aggregation/AggregationOperatorsProviderTrait.php  | 5 +++++
 4 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index fa077c02dc..266b956195 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
@@ -484,7 +484,7 @@ public function expr(): self
      * @see Builder::expr()
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
      *
-     * @param array|\Doctrine\ODM\MongoDB\Query\Expr $expression
+     * @param array|self $expression
      */
     public function exprOp($expression): self
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index a147689e9c..93c9455380 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -174,6 +174,8 @@ public function expr(): Expr
      *
      * @see Expr::exprOp()
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     *
+     * @param array|\Doctrine\ODM\MongoDB\Aggregation\Expr $expression
      */
     public function exprOp($expression): self
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index 9caabb50c3..2a7c86a78d 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
@@ -517,6 +517,8 @@ public function expr(): Expr
      *
      * @see Expr::exprOp()
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     *
+     * @param array|Expr $expression
      */
     public function exprOp($expression): self
     {
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index 21693215ee..d5dba9f6ee 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -194,6 +194,11 @@ public static function provideExpressionOperators()
                 'operator' => 'exp',
                 'args' => ['$field'],
             ],
+            'exprOp' => [
+                'expected' => ['$expr' => '$array'],
+                'operator' => 'expr',
+                'args' => ['$array'],
+            ],
             'filter' => [
                 'expected' => ['$filter' => ['input' => '$array', 'as' => '$as', 'cond' => '$cond']],
                 'operator' => 'filter',

From c319ecadad5ac5cce341300caa8dc0ef0cd9b1ae Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sun, 18 Jul 2021 04:21:09 +0200
Subject: [PATCH 04/31] + fix exprOp test

---
 .../Tests/Aggregation/AggregationOperatorsProviderTrait.php   | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index d5dba9f6ee..bcdf755c5e 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -195,9 +195,9 @@ public static function provideExpressionOperators()
                 'args' => ['$field'],
             ],
             'exprOp' => [
-                'expected' => ['$expr' => '$array'],
+                'expected' => ['$expr' => ['$eq' => ['$field', '$otherField']]],
                 'operator' => 'expr',
-                'args' => ['$array'],
+                'args' => [['$eq' => ['$field', '$otherField']]],
             ],
             'filter' => [
                 'expected' => ['$filter' => ['input' => '$array', 'as' => '$as', 'cond' => '$cond']],

From 7ba6315ce5c76cd7d133ab66c8725468da7ff3f9 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sun, 18 Jul 2021 04:25:00 +0200
Subject: [PATCH 05/31] + fix exprOp test

---
 .../Tests/Aggregation/AggregationOperatorsProviderTrait.php     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index bcdf755c5e..920dc1001e 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -196,7 +196,7 @@ public static function provideExpressionOperators()
             ],
             'exprOp' => [
                 'expected' => ['$expr' => ['$eq' => ['$field', '$otherField']]],
-                'operator' => 'expr',
+                'operator' => 'exprOp',
                 'args' => [['$eq' => ['$field', '$otherField']]],
             ],
             'filter' => [

From 06a95f1a0e13220e7b478fcc9f1b65e7ac916571 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Mon, 31 Jan 2022 04:59:43 +0100
Subject: [PATCH 06/31] + 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

---
 .../ODM/MongoDB/Aggregation/Builder.php       | 12 +++++++--
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php | 25 ++++++++-----------
 .../MongoDB/Aggregation/Stage/MatchStage.php  | 21 +++++++++++-----
 lib/Doctrine/ODM/MongoDB/Query/Builder.php    | 21 +++++++++++-----
 lib/Doctrine/ODM/MongoDB/Query/Expr.php       |  7 +++---
 .../AggregationOperatorsProviderTrait.php     |  4 +--
 6 files changed, 57 insertions(+), 33 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
index 999540d8b3..b232e9ba0a 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
@@ -165,7 +165,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();
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index 266b956195..e074b5c453 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
@@ -335,8 +335,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);
     }
@@ -475,20 +477,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();
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index a4b2219bc9..7e7a096427 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/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;
@@ -119,7 +120,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();
     }
@@ -180,20 +181,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;
     }
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index 2a7c86a78d..3d775ab4e1 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/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;
@@ -369,7 +370,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);
@@ -509,20 +510,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;
     }
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Expr.php b/lib/Doctrine/ODM/MongoDB/Query/Expr.php
index c4f8315d84..25cc496ec0 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Expr.php
+++ b/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);
     }
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index 920dc1001e..1749977a43 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -194,9 +194,9 @@ public static function provideExpressionOperators()
                 'operator' => 'exp',
                 'args' => ['$field'],
             ],
-            'exprOp' => [
+            'aggregationExpression' => [
                 'expected' => ['$expr' => ['$eq' => ['$field', '$otherField']]],
-                'operator' => 'exprOp',
+                'operator' => 'aggregationExpression',
                 'args' => [['$eq' => ['$field', '$otherField']]],
             ],
             'filter' => [

From fe79bbdd3d86410915a4a282a8aac85819e0baeb Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Tue, 8 Mar 2022 14:29:42 +0100
Subject: [PATCH 07/31] + used phpcbf on /lib

---
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php |  1 +
 .../MongoDB/Aggregation/Stage/MatchStage.php  |  5 +-
 lib/Doctrine/ODM/MongoDB/Configuration.php    |  9 ++--
 lib/Doctrine/ODM/MongoDB/DocumentManager.php  | 17 +++---
 .../ODM/MongoDB/Event/PreUpdateEventArgs.php  |  1 -
 .../ODM/MongoDB/Hydrator/HydratorFactory.php  |  3 +-
 .../MongoDB/Hydrator/HydratorInterface.php    |  5 +-
 .../ODM/MongoDB/Iterator/CachingIterator.php  |  1 -
 .../MongoDB/Iterator/HydratingIterator.php    |  2 +-
 .../ODM/MongoDB/Iterator/PrimingIterator.php  |  3 +-
 .../MongoDB/Iterator/UnrewindableIterator.php |  1 -
 .../ODM/MongoDB/Mapping/ClassMetadata.php     | 45 +++++++++-------
 .../ODM/MongoDB/Mapping/Driver/XmlDriver.php  |  1 +
 .../PersistentCollectionInterface.php         |  8 +--
 .../PersistentCollectionTrait.php             |  2 -
 .../MongoDB/Persisters/DocumentPersister.php  | 20 +++----
 .../MongoDB/Proxy/Factory/ProxyFactory.php    |  3 +-
 .../ProxyManagerClassNameResolver.php         |  2 -
 lib/Doctrine/ODM/MongoDB/Query/Builder.php    | 10 ++--
 .../Repository/AbstractRepositoryFactory.php  |  9 ++--
 .../MongoDB/Repository/DocumentRepository.php |  6 ++-
 .../MongoDB/Repository/RepositoryFactory.php  |  2 -
 lib/Doctrine/ODM/MongoDB/SchemaManager.php    | 34 ++++++------
 .../Tools/ResolveTargetDocumentListener.php   |  1 +
 lib/Doctrine/ODM/MongoDB/Types/Type.php       |  6 +--
 lib/Doctrine/ODM/MongoDB/UnitOfWork.php       | 54 +++++++------------
 .../MongoDB/Utility/LifecycleEventManager.php |  3 --
 27 files changed, 117 insertions(+), 137 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index 8d22021143..69c90308d8 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/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.
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index b0c1244ed8..4622367819 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -11,6 +11,7 @@
 use GeoJson\Geometry\Geometry;
 
 use function func_get_args;
+use function trigger_deprecation;
 
 /**
  * Fluent interface for building aggregation pipelines.
@@ -192,10 +193,10 @@ public function expr(): Expr
     /**
      * Specify $expr criteria for the current field.
      *
-     * @param array|Aggregation\Expr $expression
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
-     *
      * @see Expr::aggregationExpression()
+     *
+     * @param array|Aggregation\Expr $expression
      */
     public function aggregationExpression($expression): self
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Configuration.php b/lib/Doctrine/ODM/MongoDB/Configuration.php
index cb0a1e4bba..2a012176c7 100644
--- a/lib/Doctrine/ODM/MongoDB/Configuration.php
+++ b/lib/Doctrine/ODM/MongoDB/Configuration.php
@@ -457,6 +457,7 @@ public function setDefaultCommitOptions(array $defaultCommitOptions): void
      * Add a filter to the list of possible filters.
      *
      * @param array<string, mixed> $parameters
+     *
      * @psalm-param class-string $className
      */
     public function addFilter(string $name, string $className, array $parameters = []): void
@@ -488,9 +489,9 @@ public function getFilterParameters(string $name): array
     }
 
     /**
-     * @psalm-param class-string<ObjectRepository> $className
-     *
      * @throws MongoDBException If not is a ObjectRepository.
+     *
+     * @psalm-param class-string<ObjectRepository> $className
      */
     public function setDefaultDocumentRepositoryClassName(string $className): void
     {
@@ -512,9 +513,9 @@ public function getDefaultDocumentRepositoryClassName(): string
     }
 
     /**
-     * @psalm-param class-string<GridFSRepository> $className
-     *
      * @throws MongoDBException If the class does not implement the GridFSRepository interface.
+     *
+     * @psalm-param class-string<GridFSRepository> $className
      */
     public function setDefaultGridFSRepositoryClassName(string $className): void
     {
diff --git a/lib/Doctrine/ODM/MongoDB/DocumentManager.php b/lib/Doctrine/ODM/MongoDB/DocumentManager.php
index a335b6fae5..d366ae4b54 100644
--- a/lib/Doctrine/ODM/MongoDB/DocumentManager.php
+++ b/lib/Doctrine/ODM/MongoDB/DocumentManager.php
@@ -301,12 +301,10 @@ public function getClassNameResolver(): ClassNameResolver
      * Returns the metadata for a class.
      *
      * @param string $className The class name.
-     * @psalm-param class-string<T> $className
      *
+     * @psalm-param class-string<T> $className
      * @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
@@ -571,11 +569,11 @@ public function unlock(object $document): void
      * Gets the repository for a document class.
      *
      * @param string $className The name of the Document.
-     * @psalm-param class-string<T> $className
      *
      * @return DocumentRepository|GridFSRepository|ViewRepository  The repository.
-     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      *
+     * @psalm-param class-string<T> $className
+     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      * @template T of object
      */
     public function getRepository($className)
@@ -589,9 +587,10 @@ public function getRepository($className)
      * database.
      *
      * @param array $options Array of options to be used with batchInsert(), update() and remove()
-     * @psalm-param CommitOptions $options
      *
      * @throws MongoDBException
+     *
+     * @psalm-param CommitOptions $options
      */
     public function flush(array $options = [])
     {
@@ -608,10 +607,9 @@ public function flush(array $options = [])
      * loads itself on first access.
      *
      * @param mixed $identifier
-     * @psalm-param class-string<T> $documentName
      *
+     * @psalm-param class-string<T> $documentName
      * @psalm-return T|(T&GhostObjectInterface<T>)
-     *
      * @template T of object
      */
     public function getReference(string $documentName, $identifier): object
@@ -677,10 +675,9 @@ public function getPartialReference(string $documentName, $identifier): object
      * @param mixed  $id
      * @param int    $lockMode
      * @param int    $lockVersion
-     * @psalm-param class-string<T> $className
      *
+     * @psalm-param class-string<T> $className
      * @psalm-return T|null
-     *
      * @template T of object
      */
     public function find($className, $id, $lockMode = LockMode::NONE, $lockVersion = null): ?object
diff --git a/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php b/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
index 97e1e65ae7..a92093541b 100644
--- a/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
+++ b/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
@@ -5,7 +5,6 @@
 namespace Doctrine\ODM\MongoDB\Event;
 
 use Doctrine\ODM\MongoDB\DocumentManager;
-use Doctrine\ODM\MongoDB\UnitOfWork;
 use InvalidArgumentException;
 
 use function get_class;
diff --git a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
index c618b348bd..3136d73b22 100644
--- a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
@@ -459,9 +459,10 @@ public function hydrate(object \$document, array \$data, array \$hints = array()
      * Hydrate array of MongoDB document data into the given document object.
      *
      * @param array<string, mixed> $data
-     * @psalm-param Hints $hints Any hints to account for during reconstitution/lookup of the document.
      *
      * @return array<string, mixed>
+     *
+     * @psalm-param Hints $hints Any hints to account for during reconstitution/lookup of the document.
      */
     public function hydrate(object $document, array $data, array $hints = []): array
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
index 58fc21c07b..b2625b6cb9 100644
--- a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
+++ b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
@@ -4,8 +4,6 @@
 
 namespace Doctrine\ODM\MongoDB\Hydrator;
 
-use Doctrine\ODM\MongoDB\UnitOfWork;
-
 /**
  * The HydratorInterface defines methods all hydrator need to implement
  *
@@ -17,9 +15,10 @@ interface HydratorInterface
      * Hydrate array of MongoDB document data into the given document object.
      *
      * @param array<string, mixed> $data
-     * @psalm-param Hints $hints
      *
      * @return array<string, mixed>
+     *
+     * @psalm-param Hints $hints
      */
     public function hydrate(object $document, array $data, array $hints = []): array;
 }
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
index a38f9ac69b..99e3319a7a 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
@@ -5,7 +5,6 @@
 namespace Doctrine\ODM\MongoDB\Iterator;
 
 use Generator;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
 
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
index 9fab5bb772..89a0dfea9c 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
@@ -8,7 +8,6 @@
 use Doctrine\ODM\MongoDB\UnitOfWork;
 use Generator;
 use Iterator;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
 
@@ -43,6 +42,7 @@ final class HydratingIterator implements Iterator
     /**
      * @param Traversable<mixed, TValue> $traversable
      * @param ClassMetadata<TDocument>   $class
+     *
      * @psalm-param Hints $unitOfWorkHints
      */
     public function __construct(Traversable $traversable, UnitOfWork $unitOfWork, ClassMetadata $class, array $unitOfWorkHints = [])
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/PrimingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/PrimingIterator.php
index 5bf52f2cd7..7b8662f9bc 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/PrimingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/PrimingIterator.php
@@ -6,8 +6,6 @@
 
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\Query\ReferencePrimer;
-use Doctrine\ODM\MongoDB\UnitOfWork;
-use ReturnTypeWillChange;
 
 use function is_callable;
 use function iterator_to_array;
@@ -45,6 +43,7 @@ final class PrimingIterator implements Iterator
      * @param \Iterator<mixed, TValue>     $iterator
      * @param ClassMetadata<TDocument>     $class
      * @param array<string, callable|null> $primers
+     *
      * @psalm-param Hints $unitOfWorkHints
      */
     public function __construct(\Iterator $iterator, ClassMetadata $class, ReferencePrimer $referencePrimer, array $primers, array $unitOfWorkHints = [])
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
index 6f3ad3383c..e8f8fc1c81 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
@@ -6,7 +6,6 @@
 
 use Generator;
 use LogicException;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
 
diff --git a/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php b/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php
index ce7f5809f4..3b861e5b88 100644
--- a/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php
+++ b/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php
@@ -967,10 +967,11 @@ public function setAlsoLoadMethods(array $methods): void
      * properties.
      *
      * @param array<string, mixed>|string|null $discriminatorField
-     * @psalm-param array{name?: string, fieldName?: string}|string|null $discriminatorField
      *
      * @throws MappingException If the discriminator field conflicts with the
      *                          "name" attribute of a mapped field.
+     *
+     * @psalm-param array{name?: string, fieldName?: string}|string|null $discriminatorField
      */
     public function setDiscriminatorField($discriminatorField): void
     {
@@ -1083,6 +1084,7 @@ public function setDiscriminatorValue(string $value): void
      * Add a index for this Document.
      *
      * @param array<string, mixed> $keys
+     *
      * @psalm-param IndexKeys $keys
      * @psalm-param IndexOptions $options
      */
@@ -1134,10 +1136,11 @@ public function hasIndexes(): bool
      *
      * @param array<string, string|int> $keys
      * @param array<string, mixed>      $options
-     * @psalm-param ShardKeys $keys
-     * @psalm-param ShardOptions      $options
      *
      * @throws MappingException
+     *
+     * @psalm-param ShardKeys $keys
+     * @psalm-param ShardOptions      $options
      */
     public function setShardKey(array $keys, array $options = []): void
     {
@@ -1204,6 +1207,7 @@ public function isSharded(): bool
 
     /**
      * @return array|object|null
+     *
      * @psalm-return array<string, mixed>|object|null
      */
     public function getValidator()
@@ -1213,6 +1217,7 @@ public function getValidator()
 
     /**
      * @param array|object|null $validator
+     *
      * @psalm-param array<string, mixed>|object|null $validator
      */
     public function setValidator($validator): void
@@ -1363,9 +1368,10 @@ public function getCollection(): string
      * Sets the collection this Document is mapped to.
      *
      * @param array|string $name
-     * @psalm-param array{name: string, capped?: bool, size?: int, max?: int}|string $name
      *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param array{name: string, capped?: bool, size?: int, max?: int}|string $name
      */
     public function setCollection($name): void
     {
@@ -1463,9 +1469,9 @@ public function isMappedToCollection(): bool
     /**
      * Validates the storage strategy of a mapping for consistency
      *
-     * @psalm-param FieldMappingConfig $mapping
-     *
      * @throws MappingException
+     *
+     * @psalm-param FieldMappingConfig $mapping
      */
     private function applyStorageStrategy(array &$mapping): void
     {
@@ -1589,9 +1595,9 @@ public function addInheritedFieldMapping(array $fieldMapping): void
      *
      * @internal
      *
-     * @psalm-param AssociationFieldMapping $mapping
-     *
      * @throws MappingException
+     *
+     * @psalm-param AssociationFieldMapping $mapping
      */
     public function addInheritedAssociationMapping(array $mapping): void
     {
@@ -1792,9 +1798,9 @@ public function getFieldValue(object $document, string $field)
     /**
      * Gets the mapping of a field.
      *
-     * @psalm-return FieldMapping
-     *
      * @throws MappingException If the $fieldName is not found in the fieldMappings array.
+     *
+     * @psalm-return FieldMapping
      */
     public function getFieldMapping(string $fieldName): array
     {
@@ -1824,9 +1830,9 @@ static function ($assoc) {
      * Gets the field mapping by its DB name.
      * E.g. it returns identifier's mapping when called with _id.
      *
-     * @psalm-return FieldMapping
-     *
      * @throws MappingException
+     *
+     * @psalm-return FieldMapping
      */
     public function getFieldMappingByDbFieldName(string $dbFieldName): array
     {
@@ -1900,6 +1906,7 @@ public function isInheritanceTypeCollectionPerClass(): bool
      * Sets the mapped subclasses of this class.
      *
      * @param string[] $subclasses The names of all mapped subclasses.
+     *
      * @psalm-param class-string[] $subclasses
      */
     public function setSubclasses(array $subclasses): void
@@ -1915,6 +1922,7 @@ public function setSubclasses(array $subclasses): void
      * directParent -> directParentParent -> directParentParentParent ... -> root.
      *
      * @param string[] $classNames
+     *
      * @psalm-param list<class-string> $classNames
      */
     public function setParentClasses(array $classNames): void
@@ -1964,9 +1972,9 @@ public function isIdGeneratorNone(): bool
      * Sets the version field mapping used for versioning. Sets the default
      * value to use depending on the column type.
      *
-     * @psalm-param FieldMapping $mapping
-     *
      * @throws LockException
+     *
+     * @psalm-param FieldMapping $mapping
      */
     public function setVersionMapping(array &$mapping): void
     {
@@ -1999,9 +2007,9 @@ public function setVersionField(?string $versionField): void
      * Sets the version field mapping used for versioning. Sets the default
      * value to use depending on the column type.
      *
-     * @psalm-param FieldMapping $mapping
-     *
      * @throws LockException
+     *
+     * @psalm-param FieldMapping $mapping
      */
     public function setLockMapping(array &$mapping): void
     {
@@ -2111,11 +2119,10 @@ public function getAssociationMappedByTargetField($assocName)
     /**
      * Map a field.
      *
-     * @psalm-param FieldMappingConfig $mapping
+     * @throws MappingException
      *
+     * @psalm-param FieldMappingConfig $mapping
      * @psalm-return FieldMapping
-     *
-     * @throws MappingException
      */
     public function mapField(array $mapping): array
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php b/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
index c46a3b695f..8c0fffe9de 100644
--- a/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
+++ b/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
@@ -334,6 +334,7 @@ public function loadMetadataForClass($className, \Doctrine\Persistence\Mapping\C
 
     /**
      * @param ClassMetadata<object> $class
+     *
      * @psalm-param FieldMappingConfig $mapping
      */
     private function addFieldMapping(ClassMetadata $class, array $mapping): void
diff --git a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
index d600466a5a..407dece4f4 100644
--- a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
+++ b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
@@ -90,9 +90,9 @@ public function setDirty($dirty);
      * Sets the collection's owning document together with the AssociationMapping that
      * describes the association between the owner and the elements of the collection.
      *
-     * @psalm-param FieldMapping $mapping
-     *
      * @return void
+     *
+     * @psalm-param FieldMapping $mapping
      */
     public function setOwner(object $document, array $mapping);
 
@@ -152,15 +152,17 @@ public function getOwner(): ?object;
 
     /**
      * @return array
+     *
      * @psalm-return FieldMapping
      */
     public function getMapping();
 
     /**
      * @return ClassMetadata
-     * @psalm-return ClassMetadata<T>
      *
      * @throws MongoDBException
+     *
+     * @psalm-return ClassMetadata<T>
      */
     public function getTypeClass();
 
diff --git a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
index a6c0f17e29..de67feebed 100644
--- a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
+++ b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
@@ -7,11 +7,9 @@
 use Closure;
 use Doctrine\Common\Collections\Collection as BaseCollection;
 use Doctrine\ODM\MongoDB\DocumentManager;
-use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\MongoDBException;
 use Doctrine\ODM\MongoDB\UnitOfWork;
 use Doctrine\ODM\MongoDB\Utility\CollectionHelper;
-use ReturnTypeWillChange;
 use Traversable;
 
 use function array_combine;
diff --git a/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php b/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php
index 5b7163d670..69e38f59fa 100644
--- a/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php
+++ b/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php
@@ -207,9 +207,9 @@ public function getClassMetadata(): ClassMetadata
      *
      * If no inserts are queued, invoking this method is a NOOP.
      *
-     * @psalm-param CommitOptions $options
-     *
      * @throws DriverException
+     *
+     * @psalm-param CommitOptions $options
      */
     public function executeInserts(array $options = []): void
     {
@@ -363,9 +363,9 @@ private function executeUpsert(object $document, array $options): void
     /**
      * Updates the already persisted document if it has any new changesets.
      *
-     * @psalm-param CommitOptions $options
-     *
      * @throws LockException
+     *
+     * @psalm-param CommitOptions $options
      */
     public function update(object $document, array $options = []): void
     {
@@ -428,9 +428,9 @@ public function update(object $document, array $options = []): void
     /**
      * Removes document from mongo
      *
-     * @psalm-param CommitOptions $options
-     *
      * @throws LockException
+     *
+     * @psalm-param CommitOptions $options
      */
     public function delete(object $document, array $options = []): void
     {
@@ -482,12 +482,11 @@ public function refresh(object $document): void
      * be used to match an _id value.
      *
      * @param mixed $criteria Query criteria
-     * @psalm-param T|null $document
-     *
-     * @psalm-return T|null
      *
      * @throws LockException
      *
+     * @psalm-param T|null $document
+     * @psalm-return T|null
      * @todo Check identity map? loadById method? Try to guess whether
      *     $criteria is the id?
      */
@@ -642,9 +641,10 @@ public function unlock(object $document): void
      * @param array       $result   The query result.
      * @param object|null $document The document object to fill, if any.
      * @param array       $hints    Hints for document creation.
-     * @psalm-param T|null $document
      *
      * @return object The filled and managed document object.
+     *
+     * @psalm-param T|null $document
      * @psalm-return T
      */
     private function createDocument(array $result, ?object $document = null, array $hints = []): object
diff --git a/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php b/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
index 1fb4d0cd16..f5af38d6c2 100644
--- a/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
@@ -19,10 +19,9 @@ public function generateProxyClasses(array $classes): int;
      * the given identifier.
      *
      * @param mixed $identifier
-     * @psalm-param ClassMetadata<T> $metadata
      *
+     * @psalm-param ClassMetadata<T> $metadata
      * @psalm-return T&GhostObjectInterface<T>
-     *
      * @template T of object
      */
     public function getProxy(ClassMetadata $metadata, $identifier): GhostObjectInterface;
diff --git a/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php b/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
index 40756c682e..8b23288256 100644
--- a/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
+++ b/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
@@ -29,9 +29,7 @@ public function getRealClass(string $class): string
 
     /**
      * @psalm-param class-string<RealClassName>|class-string<ProxyInterface<RealClassName>> $className
-     *
      * @psalm-return class-string<RealClassName>
-     *
      * @psalm-template RealClassName of object
      */
     public function resolveClassName(string $className): string
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index a51aa5e59b..4ea7ca9fc4 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
@@ -26,6 +26,7 @@
 use function is_callable;
 use function is_string;
 use function strtolower;
+use function trigger_deprecation;
 
 /**
  * Query builder for ODM.
@@ -524,10 +525,10 @@ public function expr(): Expr
     /**
      * Specify $expr criteria for the current field.
      *
-     * @param array|Aggregation\Expr $expression
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
-     *
      * @see Aggregation\Expr::aggregationExpression()
+     *
+     * @param array|Aggregation\Expr $expression
      */
     public function aggregationExpression($expression): self
     {
@@ -1625,9 +1626,9 @@ public function where($javascript): self
     /**
      * Get Discriminator Values
      *
-     * @psalm-param class-string[] $classNames
-     *
      * @throws InvalidArgumentException If the number of found collections > 1.
+     *
+     * @psalm-param class-string[] $classNames
      */
     private function getDiscriminatorValues(array $classNames): array
     {
@@ -1649,6 +1650,7 @@ private function getDiscriminatorValues(array $classNames): array
 
     /**
      * @param string[]|string|null $documentName an array of document names or just one.
+     *
      * @psalm-param class-string[]|class-string|null $documentName
      */
     private function setDocumentName($documentName): void
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php b/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
index 274b567129..3a034025a7 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
@@ -27,9 +27,7 @@ abstract class AbstractRepositoryFactory implements RepositoryFactory
 
     /**
      * @psalm-param class-string<T> $documentName
-     *
      * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
-     *
      * @template T of object
      */
     public function getRepository(DocumentManager $documentManager, string $documentName): ObjectRepository
@@ -51,11 +49,10 @@ public function getRepository(DocumentManager $documentManager, string $document
     /**
      * Create a new repository instance for a document class.
      *
-     * @psalm-param class-string<T> $documentName
-     *
      * @return DocumentRepository|GridFSRepository|ViewRepository
-     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      *
+     * @psalm-param class-string<T> $documentName
+     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      * @template T of object
      */
     protected function createRepository(DocumentManager $documentManager, string $documentName): ObjectRepository
@@ -104,10 +101,10 @@ protected function createRepository(DocumentManager $documentManager, string $do
      * Instantiates requested repository.
      *
      * @param ClassMetadata<T> $metadata
-     * @psalm-param class-string<T> $repositoryClassName
      *
      * @return ObjectRepository<T>
      *
+     * @psalm-param class-string<T> $repositoryClassName
      * @template T of object
      */
     abstract protected function instantiateRepository(string $repositoryClassName, DocumentManager $documentManager, ClassMetadata $metadata): ObjectRepository;
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php b/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
index 04e3faf952..25ae8c383e 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
@@ -61,6 +61,7 @@ class DocumentRepository implements ObjectRepository, Selectable
      * @param DocumentManager $dm            The DocumentManager to use.
      * @param UnitOfWork      $uow           The UnitOfWork to use.
      * @param ClassMetadata   $classMetadata The class metadata.
+     *
      * @psalm-param ClassMetadata<T>   $classMetadata The class metadata.
      */
     public function __construct(DocumentManager $dm, UnitOfWork $uow, ClassMetadata $classMetadata)
@@ -101,10 +102,10 @@ public function clear(): void
      *
      * @param mixed $id Identifier.
      *
-     * @psalm-return T|null
-     *
      * @throws MappingException
      * @throws LockException
+     *
+     * @psalm-return T|null
      */
     public function find($id, int $lockMode = LockMode::NONE, ?int $lockVersion = null): ?object
     {
@@ -178,6 +179,7 @@ public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $
      * @param array<string, mixed>      $criteria
      *
      * @return object|null The object.
+     *
      * @psalm-return T|null
      */
     public function findOneBy(array $criteria, ?array $sort = null): ?object
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php b/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
index ee5e681ffa..ca92e2caea 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
@@ -16,9 +16,7 @@ interface RepositoryFactory
      * Gets the repository for a document class.
      *
      * @psalm-param class-string<T> $documentName
-     *
      * @psalm-return ObjectRepository<T>
-     *
      * @template T of object
      */
     public function getRepository(DocumentManager $documentManager, string $documentName): ObjectRepository;
diff --git a/lib/Doctrine/ODM/MongoDB/SchemaManager.php b/lib/Doctrine/ODM/MongoDB/SchemaManager.php
index 77ce9aaf4d..b6ed12de4b 100644
--- a/lib/Doctrine/ODM/MongoDB/SchemaManager.php
+++ b/lib/Doctrine/ODM/MongoDB/SchemaManager.php
@@ -105,9 +105,9 @@ public function updateIndexes(?int $maxTimeMs = null, ?WriteConcern $writeConcer
      * Indexes that exist in MongoDB but not the document metadata will be
      * deleted.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function updateDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -153,7 +153,6 @@ public function updateDocumentIndexes(string $documentName, ?int $maxTimeMs = nu
 
     /**
      * @psalm-param class-string $documentName
-     *
      * @psalm-return IndexMapping[]
      */
     public function getDocumentIndexes(string $documentName): array
@@ -166,7 +165,6 @@ public function getDocumentIndexes(string $documentName): array
     /**
      * @psalm-param class-string $documentName
      * @psalm-param array<class-string, bool> $visited
-     *
      * @psalm-return IndexMapping[]
      */
     private function doGetDocumentIndexes(string $documentName, array &$visited): array
@@ -268,9 +266,9 @@ private function prepareIndexes(ClassMetadata $class): array
     /**
      * Ensure the given document's indexes are created.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function ensureDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null, bool $background = false): void
     {
@@ -313,9 +311,9 @@ public function deleteIndexes(?int $maxTimeMs = null, ?WriteConcern $writeConcer
     /**
      * Delete the given document's indexes.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function deleteDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -415,9 +413,9 @@ public function createCollections(?int $maxTimeMs = null, ?WriteConcern $writeCo
     /**
      * Create the document collection for a mapped class.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function createDocumentCollection(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -494,9 +492,9 @@ public function dropCollections(?int $maxTimeMs = null, ?WriteConcern $writeConc
     /**
      * Drop the document collection for a mapped class.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function dropDocumentCollection(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -534,9 +532,9 @@ public function dropDatabases(?int $maxTimeMs = null, ?WriteConcern $writeConcer
     /**
      * Drop the document database for a mapped class.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function dropDocumentDatabase(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -755,9 +753,9 @@ public function ensureSharding(?WriteConcern $writeConcern = null): void
     /**
      * Ensure sharding for collection by document name.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws MongoDBException
+     *
+     * @psalm-param class-string $documentName
      */
     public function ensureDocumentSharding(string $documentName, ?WriteConcern $writeConcern = null): void
     {
@@ -782,9 +780,9 @@ public function ensureDocumentSharding(string $documentName, ?WriteConcern $writ
     /**
      * Enable sharding for database which contains documents with given name.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws MongoDBException
+     *
+     * @psalm-param class-string $documentName
      */
     public function enableShardingForDbByDocumentName(string $documentName): void
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php b/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
index f499cfc6a5..501c735ad0 100644
--- a/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
+++ b/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
@@ -93,6 +93,7 @@ public function loadClassMetadata(LoadClassMetadataEventArgs $args): void
 
     /**
      * @param ClassMetadata<object> $classMetadata
+     *
      * @psalm-param AssociationFieldMapping $mapping
      */
     private function remapAssociation(ClassMetadata $classMetadata, array $mapping): void
diff --git a/lib/Doctrine/ODM/MongoDB/Types/Type.php b/lib/Doctrine/ODM/MongoDB/Types/Type.php
index 17f2a56d1a..20dc99a276 100644
--- a/lib/Doctrine/ODM/MongoDB/Types/Type.php
+++ b/lib/Doctrine/ODM/MongoDB/Types/Type.php
@@ -202,10 +202,9 @@ public static function convertPHPToDatabaseValue($value)
     /**
      * Adds a custom type to the type map.
      *
-     * @psalm-param class-string $className
-     *
      * @throws MappingException
      *
+     * @psalm-param class-string $className
      * @static
      */
     public static function addType(string $name, string $className): void
@@ -230,10 +229,9 @@ public static function hasType(string $name): bool
     /**
      * Overrides an already defined type to use a different implementation.
      *
-     * @psalm-param class-string $className
-     *
      * @throws MappingException
      *
+     * @psalm-param class-string $className
      * @static
      */
     public static function overrideType(string $name, string $className): void
diff --git a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
index 106176e9e3..85da2ce714 100644
--- a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
+++ b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
@@ -25,7 +25,6 @@
 use Doctrine\Persistence\PropertyChangedListener;
 use InvalidArgumentException;
 use MongoDB\BSON\UTCDateTime;
-use MongoDB\Driver\WriteConcern;
 use ProxyManager\Proxy\GhostObjectInterface;
 use ReflectionProperty;
 use UnexpectedValueException;
@@ -354,9 +353,7 @@ public function getParentAssociation(object $document): ?array
      * Get the document persister instance for the given document name
      *
      * @psalm-param class-string<T> $documentName
-     *
      * @psalm-return Persisters\DocumentPersister<T>
-     *
      * @template T of object
      */
     public function getDocumentPersister(string $documentName): Persisters\DocumentPersister
@@ -410,6 +407,7 @@ public function setDocumentPersister(string $documentName, Persisters\DocumentPe
      * 3) All document deletions
      *
      * @param array $options Array of options to be used with batchInsert(), update() and remove()
+     *
      * @psalm-param CommitOptions $options
      */
     public function commit(array $options = []): void
@@ -577,6 +575,7 @@ private function computeScheduleUpsertsChangeSets(): void
      * Gets the changeset for a document.
      *
      * @return array array('property' => array(0 => mixed, 1 => mixed))
+     *
      * @psalm-return array<string, ChangeSet>
      */
     public function getDocumentChangeSet(object $document): array
@@ -663,7 +662,6 @@ public function getDocumentActualData(object $document): array
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function computeChangeSet(ClassMetadata $class, object $document): void
@@ -685,7 +683,6 @@ public function computeChangeSet(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     private function computeOrRecomputeChangeSet(ClassMetadata $class, object $document, bool $recompute = false): void
@@ -958,9 +955,10 @@ public function computeChangeSets(): void
      * Computes the changes of an association.
      *
      * @param mixed $value The value of the association.
-     * @psalm-param AssociationFieldMapping $assoc
      *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param AssociationFieldMapping $assoc
      */
     private function computeAssociationChanges(object $parentDocument, array $assoc, $value): void
     {
@@ -1080,11 +1078,10 @@ private function computeAssociationChanges(object $parentDocument, array $assoc,
      * because this method is invoked during a commit cycle then the change sets are added.
      * whereby changes detected in this method prevail.
      *
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException If the passed document is not MANAGED.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     public function recomputeSingleDocumentChangeSet(ClassMetadata $class, object $document): void
@@ -1108,11 +1105,10 @@ public function recomputeSingleDocumentChangeSet(ClassMetadata $class, object $d
     }
 
     /**
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException If there is something wrong with document's identifier.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     private function persistNew(ClassMetadata $class, object $document): void
@@ -1165,7 +1161,6 @@ private function persistNew(ClassMetadata $class, object $document): void
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeInserts(ClassMetadata $class, array $documents, array $options = []): void
@@ -1190,7 +1185,6 @@ private function executeInserts(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeUpserts(ClassMetadata $class, array $documents, array $options = []): void
@@ -1215,7 +1209,6 @@ private function executeUpserts(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeUpdates(ClassMetadata $class, array $documents, array $options = []): void
@@ -1246,7 +1239,6 @@ private function executeUpdates(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeDeletions(ClassMetadata $class, array $documents, array $options = []): void
@@ -1294,11 +1286,10 @@ private function executeDeletions(ClassMetadata $class, array $documents, array
      *
      * @internal
      *
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     public function scheduleForInsert(ClassMetadata $class, object $document): void
@@ -1332,11 +1323,10 @@ public function scheduleForInsert(ClassMetadata $class, object $document): void
      *
      * @internal
      *
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     public function scheduleForUpsert(ClassMetadata $class, object $document): void
@@ -1623,14 +1613,12 @@ public function removeFromIdentityMap(object $document): bool
      * @internal
      *
      * @param mixed $id Document identifier
-     * @psalm-param ClassMetadata<T> $class
-     *
-     * @psalm-return T
      *
      * @throws InvalidArgumentException If the class does not have an identifier.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-return T
      * @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
@@ -1651,15 +1639,14 @@ public function getById($id, ClassMetadata $class): object
      * @internal
      *
      * @param mixed $id Document identifier
-     * @psalm-param ClassMetadata<T> $class
      *
      * @return mixed The found document or FALSE.
-     * @psalm-return T|false
      *
      * @throws InvalidArgumentException If the class does not have an identifier.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-return T|false
      * @template T of object
-     *
      * @psalm-suppress InvalidReturnStatement, InvalidReturnType because of the inability of defining a generic property map
      */
     public function tryGetById($id, ClassMetadata $class)
@@ -1883,12 +1870,13 @@ public function merge(object $document): object
      * Executes a merge operation on a document.
      *
      * @param array<string, object> $visited
-     * @psalm-param AssociationFieldMapping|null $assoc
      *
      * @throws InvalidArgumentException If the entity instance is NEW.
      * @throws LockException If the document uses optimistic locking through a
      *                       version attribute and the version check against the
      *                       managed copy fails.
+     *
+     * @psalm-param AssociationFieldMapping|null $assoc
      */
     private function doMerge(object $document, array &$visited, ?object $prevManagedCopy = null, ?array $assoc = null): object
     {
@@ -2484,9 +2472,7 @@ public function unscheduleOrphanRemoval(object $document): void
      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
      * @psalm-param T $document
      * @psalm-param ClassMetadata<T> $class
-     *
      * @psalm-return PersistentCollectionInterface<array-key, object>
-     *
      * @template T of object
      */
     private function fixPersistentCollectionOwnership(PersistentCollectionInterface $coll, object $document, ClassMetadata $class, string $propName): PersistentCollectionInterface
@@ -2635,6 +2621,7 @@ public function isCollectionScheduledForUpdate(PersistentCollectionInterface $co
      * @internal
      *
      * @return PersistentCollectionInterface[]
+     *
      * @psalm-return array<PersistentCollectionInterface<array-key, object>>
      */
     public function getVisitedCollections(object $document): array
@@ -2650,6 +2637,7 @@ public function getVisitedCollections(object $document): array
      * @internal
      *
      * @return PersistentCollectionInterface[]
+     *
      * @psalm-return array<string, PersistentCollectionInterface<array-key, object>>
      */
     public function getScheduledCollections(object $document): array
@@ -2790,9 +2778,7 @@ public function getClassNameForAssociation(array $mapping, $data): string
      * @psalm-param array<string, mixed> $data
      * @psalm-param T|null $document
      * @psalm-param Hints $hints
-     *
      * @psalm-return T
-     *
      * @template T of object
      */
     public function getOrCreateDocument(string $className, array $data, array &$hints = [], ?object $document = null): object
diff --git a/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php b/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
index 8bf418bf16..19973aa4aa 100644
--- a/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
+++ b/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
@@ -68,7 +68,6 @@ public function postCollectionLoad(PersistentCollectionInterface $coll): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function postPersist(ClassMetadata $class, object $document): void
@@ -83,7 +82,6 @@ public function postPersist(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function postRemove(ClassMetadata $class, object $document): void
@@ -98,7 +96,6 @@ public function postRemove(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function postUpdate(ClassMetadata $class, object $document): void

From 898ce49a7781740a60d9d8a4db5fcccdd26fdb85 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Tue, 8 Mar 2022 14:44:48 +0100
Subject: [PATCH 08/31] + used phpcbf on /tests

---
 tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php  | 1 -
 .../ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php  | 6 +++---
 .../ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php      | 1 -
 3 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php b/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php
index 5783c7e9ed..494525a7e4 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php
@@ -15,7 +15,6 @@ class ClassMetadataTestUtil
 {
     /**
      * @psalm-param FieldMappingConfig $mapping
-     *
      * @psalm-return FieldMapping
      */
     public static function getFieldMapping(array $mapping): array
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php b/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php
index 8859cbdb5d..9194c59621 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php
@@ -645,8 +645,8 @@ public static function dataProviderTestWriteConcern(): array
 
     /**
      * @param int|string $writeConcern
-     * @psalm-param class-string $class
      *
+     * @psalm-param class-string $class
      * @dataProvider dataProviderTestWriteConcern
      */
     public function testExecuteInsertsRespectsWriteConcern(string $class, $writeConcern): void
@@ -669,8 +669,8 @@ public function testExecuteInsertsRespectsWriteConcern(string $class, $writeConc
 
     /**
      * @param int|string $writeConcern
-     * @psalm-param class-string $class
      *
+     * @psalm-param class-string $class
      * @dataProvider dataProviderTestWriteConcern
      */
     public function testExecuteUpsertsRespectsWriteConcern(string $class, $writeConcern): void
@@ -694,8 +694,8 @@ public function testExecuteUpsertsRespectsWriteConcern(string $class, $writeConc
 
     /**
      * @param int|string $writeConcern
-     * @psalm-param class-string $class
      *
+     * @psalm-param class-string $class
      * @dataProvider dataProviderTestWriteConcern
      */
     public function testRemoveRespectsWriteConcern(string $class, $writeConcern): void
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php
index 9af05bdb86..c934d9a91f 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php
@@ -7,7 +7,6 @@
 use Doctrine\ODM\MongoDB\Event\LifecycleEventArgs;
 use Doctrine\ODM\MongoDB\Events;
 use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
-use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\Tests\BaseTest;
 
 class GH1152Test extends BaseTest

From 5b6a368d4d8c4f935ac7d74f7a545f60c31c8a7e Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sat, 17 Jul 2021 21:41:31 +0200
Subject: [PATCH 09/31] + 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

---
 .../ODM/MongoDB/Aggregation/Builder.php       | 15 +++++-
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php | 25 +++++++++-
 .../MongoDB/Aggregation/Stage/MatchStage.php  | 48 +++++++++++++++++--
 lib/Doctrine/ODM/MongoDB/Query/Builder.php    | 29 +++++++++--
 lib/Doctrine/ODM/MongoDB/Query/Expr.php       | 13 +++++
 5 files changed, 121 insertions(+), 9 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
index 3aea4eca60..cd358d07a7 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
@@ -167,6 +167,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
      *
@@ -185,9 +193,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();
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index 519aa50056..9228640d25 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
@@ -330,6 +330,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.
      *
@@ -459,10 +467,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);
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index 863099ace1..f8b4daa51c 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -112,6 +112,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.
      *
@@ -164,12 +182,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;
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index 104598088a..f4f2752bd6 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
@@ -366,6 +366,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.
      *
@@ -493,13 +504,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;
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Expr.php b/lib/Doctrine/ODM/MongoDB/Query/Expr.php
index 9a75afcb71..c689b70244 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Expr.php
+++ b/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.
      *

From e865bd00caf27125ac93a619161eba6883465a94 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sat, 17 Jul 2021 22:02:01 +0200
Subject: [PATCH 10/31] * fix MatchStage expr revision introduced bug

---
 .../ODM/MongoDB/Aggregation/Builder.php       |  2 --
 .../MongoDB/Aggregation/Stage/MatchStage.php  | 31 ++++---------------
 2 files changed, 6 insertions(+), 27 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
index cd358d07a7..574f3b4304 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
@@ -194,8 +194,6 @@ public function execute(array $options = []): Iterator
     }
 
     /**
-     * @return Expr
-     *
      * @deprecated use createExpr instead
      */
     public function expr(): Expr
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index f8b4daa51c..6cf03844b9 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -113,21 +113,12 @@ public function all(array $values): self
     }
 
     /**
-     * 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
+     * Create a new Expr instance that can be used to build partial expressions
+     * for other operator methods.
      */
-    public function createExpr($expression): self
+    public function createExpr(): Expr
     {
-        $this->query->expr($expression);
-
-        return $this;
+        return $this->builder->matchExpr();
     }
 
     /**
@@ -182,21 +173,11 @@ public function exists(bool $bool): self
     }
 
     /**
-     * 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
+    public function expr(): Expr
     {
-        return $this->createExpr($expression);
+        return $this->createExpr();
     }
 
     /**

From 4285401f4b16cbe6f6fa2dc03211abd00065aaf3 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sun, 18 Jul 2021 02:07:37 +0200
Subject: [PATCH 11/31] + add exprOp test + add contextual missing type hint
 for exprOr

---
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php                | 2 +-
 lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php    | 2 ++
 lib/Doctrine/ODM/MongoDB/Query/Builder.php                   | 2 ++
 .../Tests/Aggregation/AggregationOperatorsProviderTrait.php  | 5 +++++
 4 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index 9228640d25..8d08bb8717 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
@@ -481,7 +481,7 @@ public function expr(): self
      * @see Builder::expr()
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
      *
-     * @param array|\Doctrine\ODM\MongoDB\Query\Expr $expression
+     * @param array|self $expression
      */
     public function exprOp($expression): self
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index 6cf03844b9..04d7c4f6ca 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -185,6 +185,8 @@ public function expr(): Expr
      *
      * @see Expr::exprOp()
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     *
+     * @param array|\Doctrine\ODM\MongoDB\Aggregation\Expr $expression
      */
     public function exprOp($expression): self
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index f4f2752bd6..2258c96434 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
@@ -517,6 +517,8 @@ public function expr(): Expr
      *
      * @see Expr::exprOp()
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     *
+     * @param array|Expr $expression
      */
     public function exprOp($expression): self
     {
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index 43e0007b17..d791534630 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -194,6 +194,11 @@ public static function provideExpressionOperators(): array
                 'operator' => 'exp',
                 'args' => ['$field'],
             ],
+            'exprOp' => [
+                'expected' => ['$expr' => '$array'],
+                'operator' => 'expr',
+                'args' => ['$array'],
+            ],
             'filter' => [
                 'expected' => ['$filter' => ['input' => '$array', 'as' => '$as', 'cond' => '$cond']],
                 'operator' => 'filter',

From eece492c36301956c7cdc41821c86429ce21fe5c Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sun, 18 Jul 2021 04:21:09 +0200
Subject: [PATCH 12/31] + fix exprOp test

---
 .../Tests/Aggregation/AggregationOperatorsProviderTrait.php   | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index d791534630..8ce04d47fb 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -195,9 +195,9 @@ public static function provideExpressionOperators(): array
                 'args' => ['$field'],
             ],
             'exprOp' => [
-                'expected' => ['$expr' => '$array'],
+                'expected' => ['$expr' => ['$eq' => ['$field', '$otherField']]],
                 'operator' => 'expr',
-                'args' => ['$array'],
+                'args' => [['$eq' => ['$field', '$otherField']]],
             ],
             'filter' => [
                 'expected' => ['$filter' => ['input' => '$array', 'as' => '$as', 'cond' => '$cond']],

From 8e4ea1b8898686514e6ceab3828a0c7e5f2f846b Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sun, 18 Jul 2021 04:25:00 +0200
Subject: [PATCH 13/31] + fix exprOp test

---
 .../Tests/Aggregation/AggregationOperatorsProviderTrait.php     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index 8ce04d47fb..3ef320a947 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -196,7 +196,7 @@ public static function provideExpressionOperators(): array
             ],
             'exprOp' => [
                 'expected' => ['$expr' => ['$eq' => ['$field', '$otherField']]],
-                'operator' => 'expr',
+                'operator' => 'exprOp',
                 'args' => [['$eq' => ['$field', '$otherField']]],
             ],
             'filter' => [

From ccaa1a4a900ab6ae91a4d8753534e5f73826a24c Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Mon, 31 Jan 2022 04:59:43 +0100
Subject: [PATCH 14/31] + 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

---
 .../ODM/MongoDB/Aggregation/Builder.php       | 12 +++++++--
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php | 25 ++++++++-----------
 .../MongoDB/Aggregation/Stage/MatchStage.php  | 21 +++++++++++-----
 lib/Doctrine/ODM/MongoDB/Query/Builder.php    | 21 +++++++++++-----
 lib/Doctrine/ODM/MongoDB/Query/Expr.php       |  7 +++---
 .../AggregationOperatorsProviderTrait.php     |  4 +--
 6 files changed, 57 insertions(+), 33 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
index 574f3b4304..36ab479e52 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
@@ -170,7 +170,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);
     }
@@ -198,7 +198,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();
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index 8d08bb8717..8d22021143 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
@@ -332,8 +332,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);
     }
@@ -472,20 +474,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();
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index 04d7c4f6ca..b0c1244ed8 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/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;
@@ -116,7 +117,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();
     }
@@ -177,20 +178,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;
     }
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index 2258c96434..1ebb0b080f 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/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;
@@ -369,7 +370,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);
@@ -509,20 +510,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;
     }
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Expr.php b/lib/Doctrine/ODM/MongoDB/Query/Expr.php
index c689b70244..9a46d97873 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Expr.php
+++ b/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);
     }
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index 3ef320a947..c7fd92f6d4 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -194,9 +194,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' => [

From 110375ef855ddfece8f664b6ef801e0753093167 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Tue, 8 Mar 2022 14:29:42 +0100
Subject: [PATCH 15/31] + rebase on newer 2.3.x

---
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php |  1 +
 .../MongoDB/Aggregation/Stage/MatchStage.php  |  5 +-
 lib/Doctrine/ODM/MongoDB/Configuration.php    |  9 ++--
 lib/Doctrine/ODM/MongoDB/DocumentManager.php  | 17 +++---
 .../ODM/MongoDB/Event/PreUpdateEventArgs.php  |  1 -
 .../ODM/MongoDB/Hydrator/HydratorFactory.php  |  3 +-
 .../MongoDB/Hydrator/HydratorInterface.php    |  5 +-
 .../ODM/MongoDB/Iterator/CachingIterator.php  |  1 -
 .../MongoDB/Iterator/HydratingIterator.php    |  2 +-
 .../MongoDB/Iterator/UnrewindableIterator.php |  1 -
 .../ODM/MongoDB/Mapping/Driver/XmlDriver.php  |  1 +
 .../PersistentCollectionInterface.php         |  8 +--
 .../PersistentCollectionTrait.php             |  2 -
 .../MongoDB/Persisters/DocumentPersister.php  | 20 +++----
 .../MongoDB/Proxy/Factory/ProxyFactory.php    |  3 +-
 .../ProxyManagerClassNameResolver.php         |  2 -
 lib/Doctrine/ODM/MongoDB/Query/Builder.php    | 10 ++--
 .../Repository/AbstractRepositoryFactory.php  |  9 ++--
 .../MongoDB/Repository/DocumentRepository.php |  6 ++-
 .../MongoDB/Repository/RepositoryFactory.php  |  2 -
 lib/Doctrine/ODM/MongoDB/SchemaManager.php    | 34 ++++++------
 .../Tools/ResolveTargetDocumentListener.php   |  1 +
 lib/Doctrine/ODM/MongoDB/Types/Type.php       |  6 +--
 lib/Doctrine/ODM/MongoDB/UnitOfWork.php       | 54 +++++++------------
 .../MongoDB/Utility/LifecycleEventManager.php |  3 --
 25 files changed, 90 insertions(+), 116 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index 8d22021143..69c90308d8 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/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.
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index b0c1244ed8..4622367819 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -11,6 +11,7 @@
 use GeoJson\Geometry\Geometry;
 
 use function func_get_args;
+use function trigger_deprecation;
 
 /**
  * Fluent interface for building aggregation pipelines.
@@ -192,10 +193,10 @@ public function expr(): Expr
     /**
      * Specify $expr criteria for the current field.
      *
-     * @param array|Aggregation\Expr $expression
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
-     *
      * @see Expr::aggregationExpression()
+     *
+     * @param array|Aggregation\Expr $expression
      */
     public function aggregationExpression($expression): self
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Configuration.php b/lib/Doctrine/ODM/MongoDB/Configuration.php
index cb0a1e4bba..2a012176c7 100644
--- a/lib/Doctrine/ODM/MongoDB/Configuration.php
+++ b/lib/Doctrine/ODM/MongoDB/Configuration.php
@@ -457,6 +457,7 @@ public function setDefaultCommitOptions(array $defaultCommitOptions): void
      * Add a filter to the list of possible filters.
      *
      * @param array<string, mixed> $parameters
+     *
      * @psalm-param class-string $className
      */
     public function addFilter(string $name, string $className, array $parameters = []): void
@@ -488,9 +489,9 @@ public function getFilterParameters(string $name): array
     }
 
     /**
-     * @psalm-param class-string<ObjectRepository> $className
-     *
      * @throws MongoDBException If not is a ObjectRepository.
+     *
+     * @psalm-param class-string<ObjectRepository> $className
      */
     public function setDefaultDocumentRepositoryClassName(string $className): void
     {
@@ -512,9 +513,9 @@ public function getDefaultDocumentRepositoryClassName(): string
     }
 
     /**
-     * @psalm-param class-string<GridFSRepository> $className
-     *
      * @throws MongoDBException If the class does not implement the GridFSRepository interface.
+     *
+     * @psalm-param class-string<GridFSRepository> $className
      */
     public function setDefaultGridFSRepositoryClassName(string $className): void
     {
diff --git a/lib/Doctrine/ODM/MongoDB/DocumentManager.php b/lib/Doctrine/ODM/MongoDB/DocumentManager.php
index a335b6fae5..d366ae4b54 100644
--- a/lib/Doctrine/ODM/MongoDB/DocumentManager.php
+++ b/lib/Doctrine/ODM/MongoDB/DocumentManager.php
@@ -301,12 +301,10 @@ public function getClassNameResolver(): ClassNameResolver
      * Returns the metadata for a class.
      *
      * @param string $className The class name.
-     * @psalm-param class-string<T> $className
      *
+     * @psalm-param class-string<T> $className
      * @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
@@ -571,11 +569,11 @@ public function unlock(object $document): void
      * Gets the repository for a document class.
      *
      * @param string $className The name of the Document.
-     * @psalm-param class-string<T> $className
      *
      * @return DocumentRepository|GridFSRepository|ViewRepository  The repository.
-     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      *
+     * @psalm-param class-string<T> $className
+     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      * @template T of object
      */
     public function getRepository($className)
@@ -589,9 +587,10 @@ public function getRepository($className)
      * database.
      *
      * @param array $options Array of options to be used with batchInsert(), update() and remove()
-     * @psalm-param CommitOptions $options
      *
      * @throws MongoDBException
+     *
+     * @psalm-param CommitOptions $options
      */
     public function flush(array $options = [])
     {
@@ -608,10 +607,9 @@ public function flush(array $options = [])
      * loads itself on first access.
      *
      * @param mixed $identifier
-     * @psalm-param class-string<T> $documentName
      *
+     * @psalm-param class-string<T> $documentName
      * @psalm-return T|(T&GhostObjectInterface<T>)
-     *
      * @template T of object
      */
     public function getReference(string $documentName, $identifier): object
@@ -677,10 +675,9 @@ public function getPartialReference(string $documentName, $identifier): object
      * @param mixed  $id
      * @param int    $lockMode
      * @param int    $lockVersion
-     * @psalm-param class-string<T> $className
      *
+     * @psalm-param class-string<T> $className
      * @psalm-return T|null
-     *
      * @template T of object
      */
     public function find($className, $id, $lockMode = LockMode::NONE, $lockVersion = null): ?object
diff --git a/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php b/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
index 97e1e65ae7..a92093541b 100644
--- a/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
+++ b/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
@@ -5,7 +5,6 @@
 namespace Doctrine\ODM\MongoDB\Event;
 
 use Doctrine\ODM\MongoDB\DocumentManager;
-use Doctrine\ODM\MongoDB\UnitOfWork;
 use InvalidArgumentException;
 
 use function get_class;
diff --git a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
index c618b348bd..3136d73b22 100644
--- a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
@@ -459,9 +459,10 @@ public function hydrate(object \$document, array \$data, array \$hints = array()
      * Hydrate array of MongoDB document data into the given document object.
      *
      * @param array<string, mixed> $data
-     * @psalm-param Hints $hints Any hints to account for during reconstitution/lookup of the document.
      *
      * @return array<string, mixed>
+     *
+     * @psalm-param Hints $hints Any hints to account for during reconstitution/lookup of the document.
      */
     public function hydrate(object $document, array $data, array $hints = []): array
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
index 58fc21c07b..b2625b6cb9 100644
--- a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
+++ b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
@@ -4,8 +4,6 @@
 
 namespace Doctrine\ODM\MongoDB\Hydrator;
 
-use Doctrine\ODM\MongoDB\UnitOfWork;
-
 /**
  * The HydratorInterface defines methods all hydrator need to implement
  *
@@ -17,9 +15,10 @@ interface HydratorInterface
      * Hydrate array of MongoDB document data into the given document object.
      *
      * @param array<string, mixed> $data
-     * @psalm-param Hints $hints
      *
      * @return array<string, mixed>
+     *
+     * @psalm-param Hints $hints
      */
     public function hydrate(object $document, array $data, array $hints = []): array;
 }
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
index a38f9ac69b..99e3319a7a 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
@@ -5,7 +5,6 @@
 namespace Doctrine\ODM\MongoDB\Iterator;
 
 use Generator;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
 
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
index 9fab5bb772..89a0dfea9c 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
@@ -8,7 +8,6 @@
 use Doctrine\ODM\MongoDB\UnitOfWork;
 use Generator;
 use Iterator;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
 
@@ -43,6 +42,7 @@ final class HydratingIterator implements Iterator
     /**
      * @param Traversable<mixed, TValue> $traversable
      * @param ClassMetadata<TDocument>   $class
+     *
      * @psalm-param Hints $unitOfWorkHints
      */
     public function __construct(Traversable $traversable, UnitOfWork $unitOfWork, ClassMetadata $class, array $unitOfWorkHints = [])
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
index 6f3ad3383c..e8f8fc1c81 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
@@ -6,7 +6,6 @@
 
 use Generator;
 use LogicException;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
 
diff --git a/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php b/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
index 0f067d4b01..1b253d52d0 100644
--- a/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
+++ b/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
@@ -334,6 +334,7 @@ public function loadMetadataForClass($className, \Doctrine\Persistence\Mapping\C
 
     /**
      * @param ClassMetadata<object> $class
+     *
      * @psalm-param FieldMappingConfig $mapping
      */
     private function addFieldMapping(ClassMetadata $class, array $mapping): void
diff --git a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
index d600466a5a..407dece4f4 100644
--- a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
+++ b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
@@ -90,9 +90,9 @@ public function setDirty($dirty);
      * Sets the collection's owning document together with the AssociationMapping that
      * describes the association between the owner and the elements of the collection.
      *
-     * @psalm-param FieldMapping $mapping
-     *
      * @return void
+     *
+     * @psalm-param FieldMapping $mapping
      */
     public function setOwner(object $document, array $mapping);
 
@@ -152,15 +152,17 @@ public function getOwner(): ?object;
 
     /**
      * @return array
+     *
      * @psalm-return FieldMapping
      */
     public function getMapping();
 
     /**
      * @return ClassMetadata
-     * @psalm-return ClassMetadata<T>
      *
      * @throws MongoDBException
+     *
+     * @psalm-return ClassMetadata<T>
      */
     public function getTypeClass();
 
diff --git a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
index 62bf3f855a..23d59ad7a9 100644
--- a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
+++ b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
@@ -7,11 +7,9 @@
 use Closure;
 use Doctrine\Common\Collections\Collection as BaseCollection;
 use Doctrine\ODM\MongoDB\DocumentManager;
-use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\MongoDBException;
 use Doctrine\ODM\MongoDB\UnitOfWork;
 use Doctrine\ODM\MongoDB\Utility\CollectionHelper;
-use ReturnTypeWillChange;
 use Traversable;
 
 use function array_combine;
diff --git a/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php b/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php
index 5b7163d670..69e38f59fa 100644
--- a/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php
+++ b/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php
@@ -207,9 +207,9 @@ public function getClassMetadata(): ClassMetadata
      *
      * If no inserts are queued, invoking this method is a NOOP.
      *
-     * @psalm-param CommitOptions $options
-     *
      * @throws DriverException
+     *
+     * @psalm-param CommitOptions $options
      */
     public function executeInserts(array $options = []): void
     {
@@ -363,9 +363,9 @@ private function executeUpsert(object $document, array $options): void
     /**
      * Updates the already persisted document if it has any new changesets.
      *
-     * @psalm-param CommitOptions $options
-     *
      * @throws LockException
+     *
+     * @psalm-param CommitOptions $options
      */
     public function update(object $document, array $options = []): void
     {
@@ -428,9 +428,9 @@ public function update(object $document, array $options = []): void
     /**
      * Removes document from mongo
      *
-     * @psalm-param CommitOptions $options
-     *
      * @throws LockException
+     *
+     * @psalm-param CommitOptions $options
      */
     public function delete(object $document, array $options = []): void
     {
@@ -482,12 +482,11 @@ public function refresh(object $document): void
      * be used to match an _id value.
      *
      * @param mixed $criteria Query criteria
-     * @psalm-param T|null $document
-     *
-     * @psalm-return T|null
      *
      * @throws LockException
      *
+     * @psalm-param T|null $document
+     * @psalm-return T|null
      * @todo Check identity map? loadById method? Try to guess whether
      *     $criteria is the id?
      */
@@ -642,9 +641,10 @@ public function unlock(object $document): void
      * @param array       $result   The query result.
      * @param object|null $document The document object to fill, if any.
      * @param array       $hints    Hints for document creation.
-     * @psalm-param T|null $document
      *
      * @return object The filled and managed document object.
+     *
+     * @psalm-param T|null $document
      * @psalm-return T
      */
     private function createDocument(array $result, ?object $document = null, array $hints = []): object
diff --git a/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php b/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
index 1fb4d0cd16..f5af38d6c2 100644
--- a/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
@@ -19,10 +19,9 @@ public function generateProxyClasses(array $classes): int;
      * the given identifier.
      *
      * @param mixed $identifier
-     * @psalm-param ClassMetadata<T> $metadata
      *
+     * @psalm-param ClassMetadata<T> $metadata
      * @psalm-return T&GhostObjectInterface<T>
-     *
      * @template T of object
      */
     public function getProxy(ClassMetadata $metadata, $identifier): GhostObjectInterface;
diff --git a/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php b/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
index 40756c682e..8b23288256 100644
--- a/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
+++ b/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
@@ -29,9 +29,7 @@ public function getRealClass(string $class): string
 
     /**
      * @psalm-param class-string<RealClassName>|class-string<ProxyInterface<RealClassName>> $className
-     *
      * @psalm-return class-string<RealClassName>
-     *
      * @psalm-template RealClassName of object
      */
     public function resolveClassName(string $className): string
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index 1ebb0b080f..c9f9dfa0a4 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
@@ -26,6 +26,7 @@
 use function is_callable;
 use function is_string;
 use function strtolower;
+use function trigger_deprecation;
 
 /**
  * Query builder for ODM.
@@ -524,10 +525,10 @@ public function expr(): Expr
     /**
      * Specify $expr criteria for the current field.
      *
-     * @param array|Aggregation\Expr $expression
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
-     *
      * @see Aggregation\Expr::aggregationExpression()
+     *
+     * @param array|Aggregation\Expr $expression
      */
     public function aggregationExpression($expression): self
     {
@@ -1625,9 +1626,9 @@ public function where($javascript): self
     /**
      * Get Discriminator Values
      *
-     * @psalm-param class-string[] $classNames
-     *
      * @throws InvalidArgumentException If the number of found collections > 1.
+     *
+     * @psalm-param class-string[] $classNames
      */
     private function getDiscriminatorValues(array $classNames): array
     {
@@ -1649,6 +1650,7 @@ private function getDiscriminatorValues(array $classNames): array
 
     /**
      * @param string[]|string|null $documentName an array of document names or just one.
+     *
      * @psalm-param class-string[]|class-string|null $documentName
      */
     private function setDocumentName($documentName): void
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php b/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
index 274b567129..3a034025a7 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
@@ -27,9 +27,7 @@ abstract class AbstractRepositoryFactory implements RepositoryFactory
 
     /**
      * @psalm-param class-string<T> $documentName
-     *
      * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
-     *
      * @template T of object
      */
     public function getRepository(DocumentManager $documentManager, string $documentName): ObjectRepository
@@ -51,11 +49,10 @@ public function getRepository(DocumentManager $documentManager, string $document
     /**
      * Create a new repository instance for a document class.
      *
-     * @psalm-param class-string<T> $documentName
-     *
      * @return DocumentRepository|GridFSRepository|ViewRepository
-     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      *
+     * @psalm-param class-string<T> $documentName
+     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      * @template T of object
      */
     protected function createRepository(DocumentManager $documentManager, string $documentName): ObjectRepository
@@ -104,10 +101,10 @@ protected function createRepository(DocumentManager $documentManager, string $do
      * Instantiates requested repository.
      *
      * @param ClassMetadata<T> $metadata
-     * @psalm-param class-string<T> $repositoryClassName
      *
      * @return ObjectRepository<T>
      *
+     * @psalm-param class-string<T> $repositoryClassName
      * @template T of object
      */
     abstract protected function instantiateRepository(string $repositoryClassName, DocumentManager $documentManager, ClassMetadata $metadata): ObjectRepository;
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php b/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
index 04e3faf952..25ae8c383e 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
@@ -61,6 +61,7 @@ class DocumentRepository implements ObjectRepository, Selectable
      * @param DocumentManager $dm            The DocumentManager to use.
      * @param UnitOfWork      $uow           The UnitOfWork to use.
      * @param ClassMetadata   $classMetadata The class metadata.
+     *
      * @psalm-param ClassMetadata<T>   $classMetadata The class metadata.
      */
     public function __construct(DocumentManager $dm, UnitOfWork $uow, ClassMetadata $classMetadata)
@@ -101,10 +102,10 @@ public function clear(): void
      *
      * @param mixed $id Identifier.
      *
-     * @psalm-return T|null
-     *
      * @throws MappingException
      * @throws LockException
+     *
+     * @psalm-return T|null
      */
     public function find($id, int $lockMode = LockMode::NONE, ?int $lockVersion = null): ?object
     {
@@ -178,6 +179,7 @@ public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $
      * @param array<string, mixed>      $criteria
      *
      * @return object|null The object.
+     *
      * @psalm-return T|null
      */
     public function findOneBy(array $criteria, ?array $sort = null): ?object
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php b/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
index ee5e681ffa..ca92e2caea 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
@@ -16,9 +16,7 @@ interface RepositoryFactory
      * Gets the repository for a document class.
      *
      * @psalm-param class-string<T> $documentName
-     *
      * @psalm-return ObjectRepository<T>
-     *
      * @template T of object
      */
     public function getRepository(DocumentManager $documentManager, string $documentName): ObjectRepository;
diff --git a/lib/Doctrine/ODM/MongoDB/SchemaManager.php b/lib/Doctrine/ODM/MongoDB/SchemaManager.php
index 77ce9aaf4d..b6ed12de4b 100644
--- a/lib/Doctrine/ODM/MongoDB/SchemaManager.php
+++ b/lib/Doctrine/ODM/MongoDB/SchemaManager.php
@@ -105,9 +105,9 @@ public function updateIndexes(?int $maxTimeMs = null, ?WriteConcern $writeConcer
      * Indexes that exist in MongoDB but not the document metadata will be
      * deleted.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function updateDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -153,7 +153,6 @@ public function updateDocumentIndexes(string $documentName, ?int $maxTimeMs = nu
 
     /**
      * @psalm-param class-string $documentName
-     *
      * @psalm-return IndexMapping[]
      */
     public function getDocumentIndexes(string $documentName): array
@@ -166,7 +165,6 @@ public function getDocumentIndexes(string $documentName): array
     /**
      * @psalm-param class-string $documentName
      * @psalm-param array<class-string, bool> $visited
-     *
      * @psalm-return IndexMapping[]
      */
     private function doGetDocumentIndexes(string $documentName, array &$visited): array
@@ -268,9 +266,9 @@ private function prepareIndexes(ClassMetadata $class): array
     /**
      * Ensure the given document's indexes are created.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function ensureDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null, bool $background = false): void
     {
@@ -313,9 +311,9 @@ public function deleteIndexes(?int $maxTimeMs = null, ?WriteConcern $writeConcer
     /**
      * Delete the given document's indexes.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function deleteDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -415,9 +413,9 @@ public function createCollections(?int $maxTimeMs = null, ?WriteConcern $writeCo
     /**
      * Create the document collection for a mapped class.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function createDocumentCollection(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -494,9 +492,9 @@ public function dropCollections(?int $maxTimeMs = null, ?WriteConcern $writeConc
     /**
      * Drop the document collection for a mapped class.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function dropDocumentCollection(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -534,9 +532,9 @@ public function dropDatabases(?int $maxTimeMs = null, ?WriteConcern $writeConcer
     /**
      * Drop the document database for a mapped class.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function dropDocumentDatabase(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -755,9 +753,9 @@ public function ensureSharding(?WriteConcern $writeConcern = null): void
     /**
      * Ensure sharding for collection by document name.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws MongoDBException
+     *
+     * @psalm-param class-string $documentName
      */
     public function ensureDocumentSharding(string $documentName, ?WriteConcern $writeConcern = null): void
     {
@@ -782,9 +780,9 @@ public function ensureDocumentSharding(string $documentName, ?WriteConcern $writ
     /**
      * Enable sharding for database which contains documents with given name.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws MongoDBException
+     *
+     * @psalm-param class-string $documentName
      */
     public function enableShardingForDbByDocumentName(string $documentName): void
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php b/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
index f499cfc6a5..501c735ad0 100644
--- a/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
+++ b/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
@@ -93,6 +93,7 @@ public function loadClassMetadata(LoadClassMetadataEventArgs $args): void
 
     /**
      * @param ClassMetadata<object> $classMetadata
+     *
      * @psalm-param AssociationFieldMapping $mapping
      */
     private function remapAssociation(ClassMetadata $classMetadata, array $mapping): void
diff --git a/lib/Doctrine/ODM/MongoDB/Types/Type.php b/lib/Doctrine/ODM/MongoDB/Types/Type.php
index da5206c2bd..e4b3b45e8b 100644
--- a/lib/Doctrine/ODM/MongoDB/Types/Type.php
+++ b/lib/Doctrine/ODM/MongoDB/Types/Type.php
@@ -200,10 +200,9 @@ public static function convertPHPToDatabaseValue($value)
     /**
      * Adds a custom type to the type map.
      *
-     * @psalm-param class-string $className
-     *
      * @throws MappingException
      *
+     * @psalm-param class-string $className
      * @static
      */
     public static function addType(string $name, string $className): void
@@ -228,10 +227,9 @@ public static function hasType(string $name): bool
     /**
      * Overrides an already defined type to use a different implementation.
      *
-     * @psalm-param class-string $className
-     *
      * @throws MappingException
      *
+     * @psalm-param class-string $className
      * @static
      */
     public static function overrideType(string $name, string $className): void
diff --git a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
index 106176e9e3..85da2ce714 100644
--- a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
+++ b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
@@ -25,7 +25,6 @@
 use Doctrine\Persistence\PropertyChangedListener;
 use InvalidArgumentException;
 use MongoDB\BSON\UTCDateTime;
-use MongoDB\Driver\WriteConcern;
 use ProxyManager\Proxy\GhostObjectInterface;
 use ReflectionProperty;
 use UnexpectedValueException;
@@ -354,9 +353,7 @@ public function getParentAssociation(object $document): ?array
      * Get the document persister instance for the given document name
      *
      * @psalm-param class-string<T> $documentName
-     *
      * @psalm-return Persisters\DocumentPersister<T>
-     *
      * @template T of object
      */
     public function getDocumentPersister(string $documentName): Persisters\DocumentPersister
@@ -410,6 +407,7 @@ public function setDocumentPersister(string $documentName, Persisters\DocumentPe
      * 3) All document deletions
      *
      * @param array $options Array of options to be used with batchInsert(), update() and remove()
+     *
      * @psalm-param CommitOptions $options
      */
     public function commit(array $options = []): void
@@ -577,6 +575,7 @@ private function computeScheduleUpsertsChangeSets(): void
      * Gets the changeset for a document.
      *
      * @return array array('property' => array(0 => mixed, 1 => mixed))
+     *
      * @psalm-return array<string, ChangeSet>
      */
     public function getDocumentChangeSet(object $document): array
@@ -663,7 +662,6 @@ public function getDocumentActualData(object $document): array
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function computeChangeSet(ClassMetadata $class, object $document): void
@@ -685,7 +683,6 @@ public function computeChangeSet(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     private function computeOrRecomputeChangeSet(ClassMetadata $class, object $document, bool $recompute = false): void
@@ -958,9 +955,10 @@ public function computeChangeSets(): void
      * Computes the changes of an association.
      *
      * @param mixed $value The value of the association.
-     * @psalm-param AssociationFieldMapping $assoc
      *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param AssociationFieldMapping $assoc
      */
     private function computeAssociationChanges(object $parentDocument, array $assoc, $value): void
     {
@@ -1080,11 +1078,10 @@ private function computeAssociationChanges(object $parentDocument, array $assoc,
      * because this method is invoked during a commit cycle then the change sets are added.
      * whereby changes detected in this method prevail.
      *
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException If the passed document is not MANAGED.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     public function recomputeSingleDocumentChangeSet(ClassMetadata $class, object $document): void
@@ -1108,11 +1105,10 @@ public function recomputeSingleDocumentChangeSet(ClassMetadata $class, object $d
     }
 
     /**
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException If there is something wrong with document's identifier.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     private function persistNew(ClassMetadata $class, object $document): void
@@ -1165,7 +1161,6 @@ private function persistNew(ClassMetadata $class, object $document): void
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeInserts(ClassMetadata $class, array $documents, array $options = []): void
@@ -1190,7 +1185,6 @@ private function executeInserts(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeUpserts(ClassMetadata $class, array $documents, array $options = []): void
@@ -1215,7 +1209,6 @@ private function executeUpserts(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeUpdates(ClassMetadata $class, array $documents, array $options = []): void
@@ -1246,7 +1239,6 @@ private function executeUpdates(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeDeletions(ClassMetadata $class, array $documents, array $options = []): void
@@ -1294,11 +1286,10 @@ private function executeDeletions(ClassMetadata $class, array $documents, array
      *
      * @internal
      *
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     public function scheduleForInsert(ClassMetadata $class, object $document): void
@@ -1332,11 +1323,10 @@ public function scheduleForInsert(ClassMetadata $class, object $document): void
      *
      * @internal
      *
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     public function scheduleForUpsert(ClassMetadata $class, object $document): void
@@ -1623,14 +1613,12 @@ public function removeFromIdentityMap(object $document): bool
      * @internal
      *
      * @param mixed $id Document identifier
-     * @psalm-param ClassMetadata<T> $class
-     *
-     * @psalm-return T
      *
      * @throws InvalidArgumentException If the class does not have an identifier.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-return T
      * @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
@@ -1651,15 +1639,14 @@ public function getById($id, ClassMetadata $class): object
      * @internal
      *
      * @param mixed $id Document identifier
-     * @psalm-param ClassMetadata<T> $class
      *
      * @return mixed The found document or FALSE.
-     * @psalm-return T|false
      *
      * @throws InvalidArgumentException If the class does not have an identifier.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-return T|false
      * @template T of object
-     *
      * @psalm-suppress InvalidReturnStatement, InvalidReturnType because of the inability of defining a generic property map
      */
     public function tryGetById($id, ClassMetadata $class)
@@ -1883,12 +1870,13 @@ public function merge(object $document): object
      * Executes a merge operation on a document.
      *
      * @param array<string, object> $visited
-     * @psalm-param AssociationFieldMapping|null $assoc
      *
      * @throws InvalidArgumentException If the entity instance is NEW.
      * @throws LockException If the document uses optimistic locking through a
      *                       version attribute and the version check against the
      *                       managed copy fails.
+     *
+     * @psalm-param AssociationFieldMapping|null $assoc
      */
     private function doMerge(object $document, array &$visited, ?object $prevManagedCopy = null, ?array $assoc = null): object
     {
@@ -2484,9 +2472,7 @@ public function unscheduleOrphanRemoval(object $document): void
      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
      * @psalm-param T $document
      * @psalm-param ClassMetadata<T> $class
-     *
      * @psalm-return PersistentCollectionInterface<array-key, object>
-     *
      * @template T of object
      */
     private function fixPersistentCollectionOwnership(PersistentCollectionInterface $coll, object $document, ClassMetadata $class, string $propName): PersistentCollectionInterface
@@ -2635,6 +2621,7 @@ public function isCollectionScheduledForUpdate(PersistentCollectionInterface $co
      * @internal
      *
      * @return PersistentCollectionInterface[]
+     *
      * @psalm-return array<PersistentCollectionInterface<array-key, object>>
      */
     public function getVisitedCollections(object $document): array
@@ -2650,6 +2637,7 @@ public function getVisitedCollections(object $document): array
      * @internal
      *
      * @return PersistentCollectionInterface[]
+     *
      * @psalm-return array<string, PersistentCollectionInterface<array-key, object>>
      */
     public function getScheduledCollections(object $document): array
@@ -2790,9 +2778,7 @@ public function getClassNameForAssociation(array $mapping, $data): string
      * @psalm-param array<string, mixed> $data
      * @psalm-param T|null $document
      * @psalm-param Hints $hints
-     *
      * @psalm-return T
-     *
      * @template T of object
      */
     public function getOrCreateDocument(string $className, array $data, array &$hints = [], ?object $document = null): object
diff --git a/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php b/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
index 8bf418bf16..19973aa4aa 100644
--- a/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
+++ b/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
@@ -68,7 +68,6 @@ public function postCollectionLoad(PersistentCollectionInterface $coll): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function postPersist(ClassMetadata $class, object $document): void
@@ -83,7 +82,6 @@ public function postPersist(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function postRemove(ClassMetadata $class, object $document): void
@@ -98,7 +96,6 @@ public function postRemove(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function postUpdate(ClassMetadata $class, object $document): void

From d1660cd49d03775cdd7df056811053efab4ba867 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Tue, 8 Mar 2022 17:49:12 +0100
Subject: [PATCH 16/31] - remove test on previously removed method
 (aggregationExpression)

---
 .../Tests/Aggregation/AggregationOperatorsProviderTrait.php  | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index c7fd92f6d4..43e0007b17 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -194,11 +194,6 @@ public static function provideExpressionOperators(): array
                 'operator' => 'exp',
                 'args' => ['$field'],
             ],
-            'aggregationExpression' => [
-                'expected' => ['$expr' => ['$eq' => ['$field', '$otherField']]],
-                'operator' => 'aggregationExpression',
-                'args' => [['$eq' => ['$field', '$otherField']]],
-            ],
             'filter' => [
                 'expected' => ['$filter' => ['input' => '$array', 'as' => '$as', 'cond' => '$cond']],
                 'operator' => 'filter',

From 0b458dee673958a33021f2e71129f5b7fdb08b1c Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sat, 17 Jul 2021 21:41:31 +0200
Subject: [PATCH 17/31] + 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

---
 .../ODM/MongoDB/Aggregation/Builder.php       | 15 +++++-
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php | 25 +++++++++-
 .../MongoDB/Aggregation/Stage/MatchStage.php  | 48 +++++++++++++++++--
 lib/Doctrine/ODM/MongoDB/Query/Builder.php    | 29 +++++++++--
 lib/Doctrine/ODM/MongoDB/Query/Expr.php       | 13 +++++
 5 files changed, 121 insertions(+), 9 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
index 3496f370c4..076ba52541 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
+++ b/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();
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index 50cebef908..c4179ba516 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/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);
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index 6fbf7f20da..16e7b6af7b 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/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;
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index 1dc91e98e2..71595c1f82 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/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;
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Expr.php b/lib/Doctrine/ODM/MongoDB/Query/Expr.php
index 3439ceeb04..d0068b9f52 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Expr.php
+++ b/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.
      *

From 839adc2aa38473fdf5e77c13d3338b99e7cad5a9 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sat, 17 Jul 2021 22:02:01 +0200
Subject: [PATCH 18/31] * fix MatchStage expr revision introduced bug

---
 .../ODM/MongoDB/Aggregation/Builder.php       |  2 --
 .../MongoDB/Aggregation/Stage/MatchStage.php  | 31 ++++---------------
 2 files changed, 6 insertions(+), 27 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
index 076ba52541..448d265d3b 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
@@ -189,8 +189,6 @@ public function execute(array $options = []): Iterator
     }
 
     /**
-     * @return Expr
-     *
      * @deprecated use createExpr instead
      */
     public function expr(): Expr
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index 16e7b6af7b..a75d5053d4 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -115,21 +115,12 @@ public function all(array $values): self
     }
 
     /**
-     * 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
+     * Create a new Expr instance that can be used to build partial expressions
+     * for other operator methods.
      */
-    public function createExpr($expression): self
+    public function createExpr(): Expr
     {
-        $this->query->expr($expression);
-
-        return $this;
+        return $this->builder->matchExpr();
     }
 
     /**
@@ -184,21 +175,11 @@ public function exists(bool $bool): self
     }
 
     /**
-     * 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
+    public function expr(): Expr
     {
-        return $this->createExpr($expression);
+        return $this->createExpr();
     }
 
     /**

From fb14785338c1b46e828516bb2f690d1f1f50e382 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sun, 18 Jul 2021 02:07:37 +0200
Subject: [PATCH 19/31] + add exprOp test + add contextual missing type hint
 for exprOr

---
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php                | 2 +-
 lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php    | 2 ++
 lib/Doctrine/ODM/MongoDB/Query/Builder.php                   | 2 ++
 .../Tests/Aggregation/AggregationOperatorsProviderTrait.php  | 5 +++++
 4 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index c4179ba516..639ee0681f 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
@@ -475,7 +475,7 @@ public function expr(): self
      * @see Builder::expr()
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
      *
-     * @param array|\Doctrine\ODM\MongoDB\Query\Expr $expression
+     * @param array|self $expression
      */
     public function exprOp($expression): self
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index a75d5053d4..935d9d87c8 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -187,6 +187,8 @@ public function expr(): Expr
      *
      * @see Expr::exprOp()
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     *
+     * @param array|\Doctrine\ODM\MongoDB\Aggregation\Expr $expression
      */
     public function exprOp($expression): self
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index 71595c1f82..ea967430a9 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
@@ -507,6 +507,8 @@ public function expr(): Expr
      *
      * @see Expr::exprOp()
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
+     *
+     * @param array|Expr $expression
      */
     public function exprOp($expression): self
     {
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index 8eec3d555a..c6abf36a93 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -192,6 +192,11 @@ public static function provideExpressionOperators(): array
                 'operator' => 'exp',
                 'args' => ['$field'],
             ],
+            'exprOp' => [
+                'expected' => ['$expr' => '$array'],
+                'operator' => 'expr',
+                'args' => ['$array'],
+            ],
             'filter' => [
                 'expected' => ['$filter' => ['input' => '$array', 'as' => '$as', 'cond' => '$cond']],
                 'operator' => 'filter',

From 906d5bc55cf55d0f0ef641dad31001010711258c Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sun, 18 Jul 2021 04:21:09 +0200
Subject: [PATCH 20/31] + fix exprOp test

---
 .../Tests/Aggregation/AggregationOperatorsProviderTrait.php   | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index c6abf36a93..409d98c842 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -193,9 +193,9 @@ public static function provideExpressionOperators(): array
                 'args' => ['$field'],
             ],
             'exprOp' => [
-                'expected' => ['$expr' => '$array'],
+                'expected' => ['$expr' => ['$eq' => ['$field', '$otherField']]],
                 'operator' => 'expr',
-                'args' => ['$array'],
+                'args' => [['$eq' => ['$field', '$otherField']]],
             ],
             'filter' => [
                 'expected' => ['$filter' => ['input' => '$array', 'as' => '$as', 'cond' => '$cond']],

From 67e6913ca9faf023e42d098100269c4d57e31ba7 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Sun, 18 Jul 2021 04:25:00 +0200
Subject: [PATCH 21/31] + fix exprOp test

---
 .../Tests/Aggregation/AggregationOperatorsProviderTrait.php     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index 409d98c842..621fcd337d 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -194,7 +194,7 @@ public static function provideExpressionOperators(): array
             ],
             'exprOp' => [
                 'expected' => ['$expr' => ['$eq' => ['$field', '$otherField']]],
-                'operator' => 'expr',
+                'operator' => 'exprOp',
                 'args' => [['$eq' => ['$field', '$otherField']]],
             ],
             'filter' => [

From b387bff11f7a86d393b42d7d6f0cff1a8e5482c2 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Mon, 31 Jan 2022 04:59:43 +0100
Subject: [PATCH 22/31] + 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

---
 .../ODM/MongoDB/Aggregation/Builder.php       | 12 +++++++--
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php | 25 ++++++++-----------
 .../MongoDB/Aggregation/Stage/MatchStage.php  | 21 +++++++++++-----
 lib/Doctrine/ODM/MongoDB/Query/Builder.php    | 21 +++++++++++-----
 lib/Doctrine/ODM/MongoDB/Query/Expr.php       |  7 +++---
 .../AggregationOperatorsProviderTrait.php     |  4 +--
 6 files changed, 57 insertions(+), 33 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
index 448d265d3b..6ad1484a8f 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
+++ b/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();
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index 639ee0681f..dcfed25cf6 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/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();
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index 935d9d87c8..3c41e560c5 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/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;
     }
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index ea967430a9..b75a37a766 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/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;
     }
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Expr.php b/lib/Doctrine/ODM/MongoDB/Query/Expr.php
index d0068b9f52..53d8a84bea 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Expr.php
+++ b/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);
     }
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index 621fcd337d..5095b830c3 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/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' => [

From 372a27b9f56cce528fff2fb9f2a7393b88b6ee8c Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Tue, 8 Mar 2022 14:29:42 +0100
Subject: [PATCH 23/31] + rebase on newer 2.3.x

---
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php |  1 +
 .../MongoDB/Aggregation/Stage/MatchStage.php  |  5 +-
 lib/Doctrine/ODM/MongoDB/DocumentManager.php  | 17 +++---
 .../ODM/MongoDB/Event/PreUpdateEventArgs.php  |  1 -
 .../ODM/MongoDB/Hydrator/HydratorFactory.php  |  3 +-
 .../MongoDB/Hydrator/HydratorInterface.php    |  5 +-
 .../ODM/MongoDB/Iterator/CachingIterator.php  |  1 -
 .../MongoDB/Iterator/HydratingIterator.php    |  2 +-
 .../MongoDB/Iterator/UnrewindableIterator.php |  1 -
 .../ODM/MongoDB/Mapping/Driver/XmlDriver.php  |  1 +
 .../PersistentCollectionInterface.php         |  8 +--
 .../PersistentCollectionTrait.php             |  2 -
 .../MongoDB/Proxy/Factory/ProxyFactory.php    |  3 +-
 .../ProxyManagerClassNameResolver.php         |  2 -
 lib/Doctrine/ODM/MongoDB/Query/Builder.php    |  1 +
 .../Repository/AbstractRepositoryFactory.php  |  9 ++--
 .../MongoDB/Repository/DocumentRepository.php |  6 ++-
 .../MongoDB/Repository/RepositoryFactory.php  |  2 -
 lib/Doctrine/ODM/MongoDB/SchemaManager.php    | 34 ++++++------
 .../Tools/ResolveTargetDocumentListener.php   |  1 +
 lib/Doctrine/ODM/MongoDB/Types/Type.php       |  6 +--
 lib/Doctrine/ODM/MongoDB/UnitOfWork.php       | 54 +++++++------------
 .../MongoDB/Utility/LifecycleEventManager.php |  3 --
 23 files changed, 70 insertions(+), 98 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index dcfed25cf6..bdbcd7d70c 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/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.
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index 3c41e560c5..1786a42c8e 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -11,6 +11,7 @@
 use GeoJson\Geometry\Geometry;
 
 use function func_get_args;
+use function trigger_deprecation;
 
 /**
  * Fluent interface for building aggregation pipelines.
@@ -194,10 +195,10 @@ public function expr(): Expr
     /**
      * Specify $expr criteria for the current field.
      *
-     * @param array|Aggregation\Expr $expression
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
-     *
      * @see Expr::aggregationExpression()
+     *
+     * @param array|Aggregation\Expr $expression
      */
     public function aggregationExpression($expression): self
     {
diff --git a/lib/Doctrine/ODM/MongoDB/DocumentManager.php b/lib/Doctrine/ODM/MongoDB/DocumentManager.php
index beafc603fe..08124630b4 100644
--- a/lib/Doctrine/ODM/MongoDB/DocumentManager.php
+++ b/lib/Doctrine/ODM/MongoDB/DocumentManager.php
@@ -279,12 +279,10 @@ public function getClassNameResolver(): ClassNameResolver
      * Returns the metadata for a class.
      *
      * @param string $className The class name.
-     * @psalm-param class-string<T> $className
      *
+     * @psalm-param class-string<T> $className
      * @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
@@ -549,11 +547,11 @@ public function unlock(object $document): void
      * Gets the repository for a document class.
      *
      * @param string $className The name of the Document.
-     * @psalm-param class-string<T> $className
      *
      * @return DocumentRepository|GridFSRepository|ViewRepository  The repository.
-     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      *
+     * @psalm-param class-string<T> $className
+     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      * @template T of object
      */
     public function getRepository($className)
@@ -567,9 +565,10 @@ public function getRepository($className)
      * database.
      *
      * @param array $options Array of options to be used with batchInsert(), update() and remove()
-     * @psalm-param CommitOptions $options
      *
      * @throws MongoDBException
+     *
+     * @psalm-param CommitOptions $options
      */
     public function flush(array $options = [])
     {
@@ -586,10 +585,9 @@ public function flush(array $options = [])
      * loads itself on first access.
      *
      * @param mixed $identifier
-     * @psalm-param class-string<T> $documentName
      *
+     * @psalm-param class-string<T> $documentName
      * @psalm-return T|(T&GhostObjectInterface<T>)
-     *
      * @template T of object
      */
     public function getReference(string $documentName, $identifier): object
@@ -657,10 +655,9 @@ public function getPartialReference(string $documentName, $identifier): object
      * @param mixed  $id
      * @param int    $lockMode
      * @param int    $lockVersion
-     * @psalm-param class-string<T> $className
      *
+     * @psalm-param class-string<T> $className
      * @psalm-return T|null
-     *
      * @template T of object
      */
     public function find($className, $id, $lockMode = LockMode::NONE, $lockVersion = null): ?object
diff --git a/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php b/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
index 85a94ec5bf..4a1a8e13a3 100644
--- a/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
+++ b/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
@@ -5,7 +5,6 @@
 namespace Doctrine\ODM\MongoDB\Event;
 
 use Doctrine\ODM\MongoDB\DocumentManager;
-use Doctrine\ODM\MongoDB\UnitOfWork;
 use InvalidArgumentException;
 
 use function get_class;
diff --git a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
index 1987dbd87d..761f4dddd9 100644
--- a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
@@ -446,9 +446,10 @@ public function hydrate(object \$document, array \$data, array \$hints = array()
      * Hydrate array of MongoDB document data into the given document object.
      *
      * @param array<string, mixed> $data
-     * @psalm-param Hints $hints Any hints to account for during reconstitution/lookup of the document.
      *
      * @return array<string, mixed>
+     *
+     * @psalm-param Hints $hints Any hints to account for during reconstitution/lookup of the document.
      */
     public function hydrate(object $document, array $data, array $hints = []): array
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
index 58fc21c07b..b2625b6cb9 100644
--- a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
+++ b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
@@ -4,8 +4,6 @@
 
 namespace Doctrine\ODM\MongoDB\Hydrator;
 
-use Doctrine\ODM\MongoDB\UnitOfWork;
-
 /**
  * The HydratorInterface defines methods all hydrator need to implement
  *
@@ -17,9 +15,10 @@ interface HydratorInterface
      * Hydrate array of MongoDB document data into the given document object.
      *
      * @param array<string, mixed> $data
-     * @psalm-param Hints $hints
      *
      * @return array<string, mixed>
+     *
+     * @psalm-param Hints $hints
      */
     public function hydrate(object $document, array $data, array $hints = []): array;
 }
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
index cfb6d4c022..257c6acd12 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
@@ -6,7 +6,6 @@
 
 use Countable;
 use Generator;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
 
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
index 7c8319df59..6450028c84 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
@@ -8,7 +8,6 @@
 use Doctrine\ODM\MongoDB\UnitOfWork;
 use Generator;
 use Iterator;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
 
@@ -42,6 +41,7 @@ final class HydratingIterator implements Iterator
     /**
      * @param Traversable<mixed, TValue> $traversable
      * @param ClassMetadata<TDocument>   $class
+     *
      * @psalm-param Hints $unitOfWorkHints
      */
     public function __construct(Traversable $traversable, UnitOfWork $unitOfWork, ClassMetadata $class, array $unitOfWorkHints = [])
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
index 9e50eff62b..c838203f14 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
@@ -6,7 +6,6 @@
 
 use Generator;
 use LogicException;
-use ReturnTypeWillChange;
 use RuntimeException;
 use Traversable;
 
diff --git a/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php b/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
index 7695f5b4e0..0471bdb14c 100644
--- a/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
+++ b/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
@@ -341,6 +341,7 @@ public function loadMetadataForClass($className, \Doctrine\Persistence\Mapping\C
 
     /**
      * @param ClassMetadata<object> $class
+     *
      * @psalm-param FieldMappingConfig $mapping
      */
     private function addFieldMapping(ClassMetadata $class, array $mapping): void
diff --git a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
index cee160dfe7..377ab98011 100644
--- a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
+++ b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
@@ -92,9 +92,9 @@ public function setDirty($dirty);
      * Sets the collection's owning document together with the AssociationMapping that
      * describes the association between the owner and the elements of the collection.
      *
-     * @psalm-param FieldMapping $mapping
-     *
      * @return void
+     *
+     * @psalm-param FieldMapping $mapping
      */
     public function setOwner(object $document, array $mapping);
 
@@ -154,15 +154,17 @@ public function getOwner(): ?object;
 
     /**
      * @return array
+     *
      * @psalm-return FieldMapping
      */
     public function getMapping();
 
     /**
      * @return ClassMetadata
-     * @psalm-return ClassMetadata<T>
      *
      * @throws MongoDBException
+     *
+     * @psalm-return ClassMetadata<T>
      */
     public function getTypeClass();
 
diff --git a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
index c538336958..56ee2824fc 100644
--- a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
+++ b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
@@ -8,11 +8,9 @@
 use Closure;
 use Doctrine\Common\Collections\Collection as BaseCollection;
 use Doctrine\ODM\MongoDB\DocumentManager;
-use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\MongoDBException;
 use Doctrine\ODM\MongoDB\UnitOfWork;
 use Doctrine\ODM\MongoDB\Utility\CollectionHelper;
-use ReturnTypeWillChange;
 use Traversable;
 
 use function array_combine;
diff --git a/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php b/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
index 1fb4d0cd16..f5af38d6c2 100644
--- a/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
@@ -19,10 +19,9 @@ public function generateProxyClasses(array $classes): int;
      * the given identifier.
      *
      * @param mixed $identifier
-     * @psalm-param ClassMetadata<T> $metadata
      *
+     * @psalm-param ClassMetadata<T> $metadata
      * @psalm-return T&GhostObjectInterface<T>
-     *
      * @template T of object
      */
     public function getProxy(ClassMetadata $metadata, $identifier): GhostObjectInterface;
diff --git a/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php b/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
index 910f539ce1..2cea022bd0 100644
--- a/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
+++ b/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
@@ -28,9 +28,7 @@ public function getRealClass(string $class): string
 
     /**
      * @psalm-param class-string<RealClassName>|class-string<ProxyInterface<RealClassName>> $className
-     *
      * @psalm-return class-string<RealClassName>
-     *
      * @psalm-template RealClassName of object
      */
     public function resolveClassName(string $className): string
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index b75a37a766..2ece528aa9 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
@@ -26,6 +26,7 @@
 use function is_callable;
 use function is_string;
 use function strtolower;
+use function trigger_deprecation;
 
 /**
  * Query builder for ODM.
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php b/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
index 065ba26356..7bce208365 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
@@ -27,9 +27,7 @@ abstract class AbstractRepositoryFactory implements RepositoryFactory
 
     /**
      * @psalm-param class-string<T> $documentName
-     *
      * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
-     *
      * @template T of object
      */
     public function getRepository(DocumentManager $documentManager, string $documentName): ObjectRepository
@@ -51,11 +49,10 @@ public function getRepository(DocumentManager $documentManager, string $document
     /**
      * Create a new repository instance for a document class.
      *
-     * @psalm-param class-string<T> $documentName
-     *
      * @return DocumentRepository|GridFSRepository|ViewRepository
-     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      *
+     * @psalm-param class-string<T> $documentName
+     * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
      * @template T of object
      */
     protected function createRepository(DocumentManager $documentManager, string $documentName): ObjectRepository
@@ -104,10 +101,10 @@ protected function createRepository(DocumentManager $documentManager, string $do
      * Instantiates requested repository.
      *
      * @param ClassMetadata<T> $metadata
-     * @psalm-param class-string<T> $repositoryClassName
      *
      * @return ObjectRepository<T>
      *
+     * @psalm-param class-string<T> $repositoryClassName
      * @template T of object
      */
     abstract protected function instantiateRepository(string $repositoryClassName, DocumentManager $documentManager, ClassMetadata $metadata): ObjectRepository;
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php b/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
index 5305f896d2..2b767e02d6 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
@@ -61,6 +61,7 @@ class DocumentRepository implements ObjectRepository, Selectable
      * @param DocumentManager $dm            The DocumentManager to use.
      * @param UnitOfWork      $uow           The UnitOfWork to use.
      * @param ClassMetadata   $classMetadata The class metadata.
+     *
      * @psalm-param ClassMetadata<T>   $classMetadata The class metadata.
      */
     public function __construct(DocumentManager $dm, UnitOfWork $uow, ClassMetadata $classMetadata)
@@ -101,10 +102,10 @@ public function clear(): void
      *
      * @param mixed $id Identifier.
      *
-     * @psalm-return T|null
-     *
      * @throws MappingException
      * @throws LockException
+     *
+     * @psalm-return T|null
      */
     public function find($id, int $lockMode = LockMode::NONE, ?int $lockVersion = null): ?object
     {
@@ -181,6 +182,7 @@ public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $
      * @param array<string, mixed>      $criteria
      *
      * @return object|null The object.
+     *
      * @psalm-return T|null
      */
     public function findOneBy(array $criteria, ?array $sort = null): ?object
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php b/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
index ee5e681ffa..ca92e2caea 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
@@ -16,9 +16,7 @@ interface RepositoryFactory
      * Gets the repository for a document class.
      *
      * @psalm-param class-string<T> $documentName
-     *
      * @psalm-return ObjectRepository<T>
-     *
      * @template T of object
      */
     public function getRepository(DocumentManager $documentManager, string $documentName): ObjectRepository;
diff --git a/lib/Doctrine/ODM/MongoDB/SchemaManager.php b/lib/Doctrine/ODM/MongoDB/SchemaManager.php
index 64bcbfdf70..bf00a15944 100644
--- a/lib/Doctrine/ODM/MongoDB/SchemaManager.php
+++ b/lib/Doctrine/ODM/MongoDB/SchemaManager.php
@@ -104,9 +104,9 @@ public function updateIndexes(?int $maxTimeMs = null, ?WriteConcern $writeConcer
      * Indexes that exist in MongoDB but not the document metadata will be
      * deleted.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function updateDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -152,7 +152,6 @@ public function updateDocumentIndexes(string $documentName, ?int $maxTimeMs = nu
 
     /**
      * @psalm-param class-string $documentName
-     *
      * @psalm-return IndexMapping[]
      */
     public function getDocumentIndexes(string $documentName): array
@@ -165,7 +164,6 @@ public function getDocumentIndexes(string $documentName): array
     /**
      * @psalm-param class-string $documentName
      * @psalm-param array<class-string, bool> $visited
-     *
      * @psalm-return IndexMapping[]
      */
     private function doGetDocumentIndexes(string $documentName, array &$visited): array
@@ -267,9 +265,9 @@ private function prepareIndexes(ClassMetadata $class): array
     /**
      * Ensure the given document's indexes are created.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function ensureDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null, bool $background = false): void
     {
@@ -312,9 +310,9 @@ public function deleteIndexes(?int $maxTimeMs = null, ?WriteConcern $writeConcer
     /**
      * Delete the given document's indexes.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function deleteDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -414,9 +412,9 @@ public function createCollections(?int $maxTimeMs = null, ?WriteConcern $writeCo
     /**
      * Create the document collection for a mapped class.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function createDocumentCollection(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -493,9 +491,9 @@ public function dropCollections(?int $maxTimeMs = null, ?WriteConcern $writeConc
     /**
      * Drop the document collection for a mapped class.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function dropDocumentCollection(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -533,9 +531,9 @@ public function dropDatabases(?int $maxTimeMs = null, ?WriteConcern $writeConcer
     /**
      * Drop the document database for a mapped class.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param class-string $documentName
      */
     public function dropDocumentDatabase(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -755,9 +753,9 @@ public function ensureSharding(?WriteConcern $writeConcern = null): void
     /**
      * Ensure sharding for collection by document name.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws MongoDBException
+     *
+     * @psalm-param class-string $documentName
      */
     public function ensureDocumentSharding(string $documentName, ?WriteConcern $writeConcern = null): void
     {
@@ -782,9 +780,9 @@ public function ensureDocumentSharding(string $documentName, ?WriteConcern $writ
     /**
      * Enable sharding for database which contains documents with given name.
      *
-     * @psalm-param class-string $documentName
-     *
      * @throws MongoDBException
+     *
+     * @psalm-param class-string $documentName
      */
     public function enableShardingForDbByDocumentName(string $documentName): void
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php b/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
index 31bb5affd9..f70cb41e9c 100644
--- a/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
+++ b/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
@@ -90,6 +90,7 @@ public function loadClassMetadata(LoadClassMetadataEventArgs $args): void
 
     /**
      * @param ClassMetadata<object> $classMetadata
+     *
      * @psalm-param AssociationFieldMapping $mapping
      */
     private function remapAssociation(ClassMetadata $classMetadata, array $mapping): void
diff --git a/lib/Doctrine/ODM/MongoDB/Types/Type.php b/lib/Doctrine/ODM/MongoDB/Types/Type.php
index d6f2b4636d..123f2f4f37 100644
--- a/lib/Doctrine/ODM/MongoDB/Types/Type.php
+++ b/lib/Doctrine/ODM/MongoDB/Types/Type.php
@@ -200,10 +200,9 @@ public static function convertPHPToDatabaseValue($value)
     /**
      * Adds a custom type to the type map.
      *
-     * @psalm-param class-string $className
-     *
      * @throws MappingException
      *
+     * @psalm-param class-string $className
      * @static
      */
     public static function addType(string $name, string $className): void
@@ -228,10 +227,9 @@ public static function hasType(string $name): bool
     /**
      * Overrides an already defined type to use a different implementation.
      *
-     * @psalm-param class-string $className
-     *
      * @throws MappingException
      *
+     * @psalm-param class-string $className
      * @static
      */
     public static function overrideType(string $name, string $className): void
diff --git a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
index 2dbb82a82e..3030102ab9 100644
--- a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
+++ b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
@@ -25,7 +25,6 @@
 use Doctrine\Persistence\PropertyChangedListener;
 use InvalidArgumentException;
 use MongoDB\BSON\UTCDateTime;
-use MongoDB\Driver\WriteConcern;
 use ProxyManager\Proxy\GhostObjectInterface;
 use ReflectionProperty;
 use UnexpectedValueException;
@@ -332,9 +331,7 @@ public function getParentAssociation(object $document): ?array
      * Get the document persister instance for the given document name
      *
      * @psalm-param class-string<T> $documentName
-     *
      * @psalm-return Persisters\DocumentPersister<T>
-     *
      * @template T of object
      */
     public function getDocumentPersister(string $documentName): Persisters\DocumentPersister
@@ -389,6 +386,7 @@ public function setDocumentPersister(string $documentName, Persisters\DocumentPe
      * 3) All document deletions
      *
      * @param array $options Array of options to be used with batchInsert(), update() and remove()
+     *
      * @psalm-param CommitOptions $options
      */
     public function commit(array $options = []): void
@@ -550,6 +548,7 @@ private function computeScheduleUpsertsChangeSets(): void
      * Gets the changeset for a document.
      *
      * @return array array('property' => array(0 => mixed, 1 => mixed))
+     *
      * @psalm-return array<string, ChangeSet>
      */
     public function getDocumentChangeSet(object $document): array
@@ -636,7 +635,6 @@ public function getDocumentActualData(object $document): array
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function computeChangeSet(ClassMetadata $class, object $document): void
@@ -658,7 +656,6 @@ public function computeChangeSet(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     private function computeOrRecomputeChangeSet(ClassMetadata $class, object $document, bool $recompute = false): void
@@ -929,9 +926,10 @@ public function computeChangeSets(): void
      * Computes the changes of an association.
      *
      * @param mixed $value The value of the association.
-     * @psalm-param AssociationFieldMapping $assoc
      *
      * @throws InvalidArgumentException
+     *
+     * @psalm-param AssociationFieldMapping $assoc
      */
     private function computeAssociationChanges(object $parentDocument, array $assoc, $value): void
     {
@@ -1051,11 +1049,10 @@ private function computeAssociationChanges(object $parentDocument, array $assoc,
      * because this method is invoked during a commit cycle then the change sets are added.
      * whereby changes detected in this method prevail.
      *
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException If the passed document is not MANAGED.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     public function recomputeSingleDocumentChangeSet(ClassMetadata $class, object $document): void
@@ -1079,11 +1076,10 @@ public function recomputeSingleDocumentChangeSet(ClassMetadata $class, object $d
     }
 
     /**
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException If there is something wrong with document's identifier.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     private function persistNew(ClassMetadata $class, object $document): void
@@ -1136,7 +1132,6 @@ private function persistNew(ClassMetadata $class, object $document): void
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeInserts(ClassMetadata $class, array $documents, array $options = []): void
@@ -1161,7 +1156,6 @@ private function executeInserts(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeUpserts(ClassMetadata $class, array $documents, array $options = []): void
@@ -1186,7 +1180,6 @@ private function executeUpserts(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeUpdates(ClassMetadata $class, array $documents, array $options = []): void
@@ -1217,7 +1210,6 @@ private function executeUpdates(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
-     *
      * @template T of object
      */
     private function executeDeletions(ClassMetadata $class, array $documents, array $options = []): void
@@ -1265,11 +1257,10 @@ private function executeDeletions(ClassMetadata $class, array $documents, array
      *
      * @internal
      *
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     public function scheduleForInsert(ClassMetadata $class, object $document): void
@@ -1303,11 +1294,10 @@ public function scheduleForInsert(ClassMetadata $class, object $document): void
      *
      * @internal
      *
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-param T $document
-     *
      * @throws InvalidArgumentException
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-param T $document
      * @template T of object
      */
     public function scheduleForUpsert(ClassMetadata $class, object $document): void
@@ -1594,14 +1584,12 @@ public function removeFromIdentityMap(object $document): bool
      * @internal
      *
      * @param mixed $id Document identifier
-     * @psalm-param ClassMetadata<T> $class
-     *
-     * @psalm-return T
      *
      * @throws InvalidArgumentException If the class does not have an identifier.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-return T
      * @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
@@ -1622,15 +1610,14 @@ public function getById($id, ClassMetadata $class): object
      * @internal
      *
      * @param mixed $id Document identifier
-     * @psalm-param ClassMetadata<T> $class
      *
      * @return mixed The found document or FALSE.
-     * @psalm-return T|false
      *
      * @throws InvalidArgumentException If the class does not have an identifier.
      *
+     * @psalm-param ClassMetadata<T> $class
+     * @psalm-return T|false
      * @template T of object
-     *
      * @psalm-suppress InvalidReturnStatement, InvalidReturnType because of the inability of defining a generic property map
      */
     public function tryGetById($id, ClassMetadata $class)
@@ -1854,12 +1841,13 @@ public function merge(object $document): object
      * Executes a merge operation on a document.
      *
      * @param array<string, object> $visited
-     * @psalm-param AssociationFieldMapping|null $assoc
      *
      * @throws InvalidArgumentException If the entity instance is NEW.
      * @throws LockException If the document uses optimistic locking through a
      *                       version attribute and the version check against the
      *                       managed copy fails.
+     *
+     * @psalm-param AssociationFieldMapping|null $assoc
      */
     private function doMerge(object $document, array &$visited, ?object $prevManagedCopy = null, ?array $assoc = null): object
     {
@@ -2445,9 +2433,7 @@ public function unscheduleOrphanRemoval(object $document): void
      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
      * @psalm-param T $document
      * @psalm-param ClassMetadata<T> $class
-     *
      * @psalm-return PersistentCollectionInterface<array-key, object>
-     *
      * @template T of object
      */
     private function fixPersistentCollectionOwnership(PersistentCollectionInterface $coll, object $document, ClassMetadata $class, string $propName): PersistentCollectionInterface
@@ -2596,6 +2582,7 @@ public function isCollectionScheduledForUpdate(PersistentCollectionInterface $co
      * @internal
      *
      * @return PersistentCollectionInterface[]
+     *
      * @psalm-return array<PersistentCollectionInterface<array-key, object>>
      */
     public function getVisitedCollections(object $document): array
@@ -2611,6 +2598,7 @@ public function getVisitedCollections(object $document): array
      * @internal
      *
      * @return PersistentCollectionInterface[]
+     *
      * @psalm-return array<string, PersistentCollectionInterface<array-key, object>>
      */
     public function getScheduledCollections(object $document): array
@@ -2751,9 +2739,7 @@ public function getClassNameForAssociation(array $mapping, $data): string
      * @psalm-param array<string, mixed> $data
      * @psalm-param T|null $document
      * @psalm-param Hints $hints
-     *
      * @psalm-return T
-     *
      * @template T of object
      */
     public function getOrCreateDocument(string $className, array $data, array &$hints = [], ?object $document = null): object
diff --git a/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php b/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
index a2a70ca5e3..ff632f15de 100644
--- a/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
+++ b/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
@@ -65,7 +65,6 @@ public function postCollectionLoad(PersistentCollectionInterface $coll): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function postPersist(ClassMetadata $class, object $document): void
@@ -80,7 +79,6 @@ public function postPersist(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function postRemove(ClassMetadata $class, object $document): void
@@ -95,7 +93,6 @@ public function postRemove(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
-     *
      * @template T of object
      */
     public function postUpdate(ClassMetadata $class, object $document): void

From 9d5845cb438e0a9996ad266bc488e3a500362dad Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Tue, 8 Mar 2022 14:44:48 +0100
Subject: [PATCH 24/31] + used phpcbf on /tests

---
 tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php  | 1 -
 .../ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php  | 6 +++---
 .../ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php      | 1 -
 3 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php b/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php
index 5783c7e9ed..494525a7e4 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php
@@ -15,7 +15,6 @@ class ClassMetadataTestUtil
 {
     /**
      * @psalm-param FieldMappingConfig $mapping
-     *
      * @psalm-return FieldMapping
      */
     public static function getFieldMapping(array $mapping): array
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php b/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php
index 20ae2fe767..55163071ba 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php
@@ -645,8 +645,8 @@ public static function dataProviderTestWriteConcern(): array
 
     /**
      * @param int|string $writeConcern
-     * @psalm-param class-string $class
      *
+     * @psalm-param class-string $class
      * @dataProvider dataProviderTestWriteConcern
      */
     public function testExecuteInsertsRespectsWriteConcern(string $class, $writeConcern): void
@@ -669,8 +669,8 @@ public function testExecuteInsertsRespectsWriteConcern(string $class, $writeConc
 
     /**
      * @param int|string $writeConcern
-     * @psalm-param class-string $class
      *
+     * @psalm-param class-string $class
      * @dataProvider dataProviderTestWriteConcern
      */
     public function testExecuteUpsertsRespectsWriteConcern(string $class, $writeConcern): void
@@ -694,8 +694,8 @@ public function testExecuteUpsertsRespectsWriteConcern(string $class, $writeConc
 
     /**
      * @param int|string $writeConcern
-     * @psalm-param class-string $class
      *
+     * @psalm-param class-string $class
      * @dataProvider dataProviderTestWriteConcern
      */
     public function testRemoveRespectsWriteConcern(string $class, $writeConcern): void
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php
index 84e8625469..cbbaf39b50 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php
@@ -7,7 +7,6 @@
 use Doctrine\ODM\MongoDB\Event\LifecycleEventArgs;
 use Doctrine\ODM\MongoDB\Events;
 use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
-use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\Tests\BaseTest;
 
 class GH1152Test extends BaseTest

From c30899b651d3179665b2d22555b28be0a8b4d0c0 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@webmarketing-booster.com>
Date: Tue, 8 Mar 2022 17:49:12 +0100
Subject: [PATCH 25/31] - remove test on previously removed method
 (aggregationExpression)

---
 .../Tests/Aggregation/AggregationOperatorsProviderTrait.php  | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
index 5095b830c3..8eec3d555a 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/AggregationOperatorsProviderTrait.php
@@ -192,11 +192,6 @@ public static function provideExpressionOperators(): array
                 'operator' => 'exp',
                 'args' => ['$field'],
             ],
-            'aggregationExpression' => [
-                'expected' => ['$expr' => ['$eq' => ['$field', '$otherField']]],
-                'operator' => 'aggregationExpression',
-                'args' => [['$eq' => ['$field', '$otherField']]],
-            ],
             'filter' => [
                 'expected' => ['$filter' => ['input' => '$array', 'as' => '$as', 'cond' => '$cond']],
                 'operator' => 'filter',

From a3dfb0d2082a7acbf2fdbb0760dd732d556c2429 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@outlook.com>
Date: Fri, 4 Nov 2022 11:34:30 +0100
Subject: [PATCH 26/31] + minor documentation updates

---
 lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php          | 4 ++--
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php             | 4 ++--
 lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php | 2 +-
 lib/Doctrine/ODM/MongoDB/Query/Builder.php                | 4 ++--
 4 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
index 6ad1484a8f..9b38189483 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
@@ -189,13 +189,13 @@ public function execute(array $options = []): Iterator
     }
 
     /**
-     * @deprecated use createExpr instead
+     * @deprecated use createAggregationExpression instead
      */
     public function expr(): Expr
     {
         trigger_deprecation(
             'doctrine/mongodb-odm',
-            '2.3',
+            '2.5',
             'The "%s" method is deprecated. Please use "%s::createAggregationExpression" instead.',
             __METHOD__,
             static::class
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index bdbcd7d70c..29e2d2fadb 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
@@ -465,13 +465,13 @@ public function exp($exponent): self
     /**
      * Returns a new expression object
      *
-     * @deprecated use createExpr instead
+     * @deprecated use createAggregationExpression instead
      */
     public function expr(): self
     {
         trigger_deprecation(
             'doctrine/mongodb-odm',
-            '2.3',
+            '2.5',
             'The "%s" method is deprecated. Please use "%s::createAggregationExpression" instead.',
             __METHOD__,
             static::class
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index 1786a42c8e..aa862c3d80 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -183,7 +183,7 @@ public function expr(): Expr
     {
         trigger_deprecation(
             'doctrine/mongodb-odm',
-            '2.3',
+            '2.5',
             'The "%s" method is deprecated. Please use "%s::createQueryExpression" instead.',
             __METHOD__,
             static::class
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index 2ece528aa9..75ff2d94ec 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
@@ -497,13 +497,13 @@ 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
+     * @deprecated use createQueryExpression instead
      */
     public function expr(): Expr
     {
         trigger_deprecation(
             'doctrine/mongodb-odm',
-            '2.3',
+            '2.5',
             'The "%s" method is deprecated. Please use "%s::createQueryExpression" instead.',
             __METHOD__,
             static::class

From 9746da5291519fbf2befb0ecbe0c6cac70641baa Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@outlook.com>
Date: Fri, 4 Nov 2022 12:39:06 +0100
Subject: [PATCH 27/31] + applied vendor/bin/phpcbf

---
 lib/Doctrine/ODM/MongoDB/DocumentManager.php  | 16 +++---
 .../ODM/MongoDB/Hydrator/HydratorFactory.php  |  3 +-
 .../MongoDB/Hydrator/HydratorInterface.php    |  3 +-
 .../MongoDB/Iterator/HydratingIterator.php    |  1 -
 .../ODM/MongoDB/Mapping/Driver/XmlDriver.php  |  1 -
 .../PersistentCollectionInterface.php         |  8 ++-
 .../MongoDB/Proxy/Factory/ProxyFactory.php    |  3 +-
 .../ProxyManagerClassNameResolver.php         |  2 +
 lib/Doctrine/ODM/MongoDB/Query/Builder.php    |  4 +-
 .../Repository/AbstractRepositoryFactory.php  |  9 ++--
 .../MongoDB/Repository/DocumentRepository.php |  6 +--
 .../MongoDB/Repository/RepositoryFactory.php  |  2 +
 lib/Doctrine/ODM/MongoDB/SchemaManager.php    | 34 +++++++------
 .../Tools/ResolveTargetDocumentListener.php   |  1 -
 lib/Doctrine/ODM/MongoDB/Types/Type.php       |  6 ++-
 lib/Doctrine/ODM/MongoDB/UnitOfWork.php       | 51 +++++++++++--------
 .../MongoDB/Utility/LifecycleEventManager.php |  3 ++
 .../MongoDB/Tests/ClassMetadataTestUtil.php   |  1 +
 .../Functional/DocumentPersisterTest.php      |  6 +--
 19 files changed, 90 insertions(+), 70 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/DocumentManager.php b/lib/Doctrine/ODM/MongoDB/DocumentManager.php
index 08124630b4..de7547f895 100644
--- a/lib/Doctrine/ODM/MongoDB/DocumentManager.php
+++ b/lib/Doctrine/ODM/MongoDB/DocumentManager.php
@@ -279,9 +279,10 @@ public function getClassNameResolver(): ClassNameResolver
      * Returns the metadata for a class.
      *
      * @param string $className The class name.
-     *
      * @psalm-param class-string<T> $className
+     *
      * @psalm-return ClassMetadata<T>
+     *
      * @template T of object
      * @psalm-suppress InvalidReturnType, InvalidReturnStatement see https://github.com/vimeo/psalm/issues/5788
      */
@@ -547,11 +548,11 @@ public function unlock(object $document): void
      * Gets the repository for a document class.
      *
      * @param string $className The name of the Document.
+     * @psalm-param class-string<T> $className
      *
      * @return DocumentRepository|GridFSRepository|ViewRepository  The repository.
-     *
-     * @psalm-param class-string<T> $className
      * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
+     *
      * @template T of object
      */
     public function getRepository($className)
@@ -565,10 +566,9 @@ public function getRepository($className)
      * database.
      *
      * @param array $options Array of options to be used with batchInsert(), update() and remove()
+     * @psalm-param CommitOptions $options
      *
      * @throws MongoDBException
-     *
-     * @psalm-param CommitOptions $options
      */
     public function flush(array $options = [])
     {
@@ -585,9 +585,10 @@ public function flush(array $options = [])
      * loads itself on first access.
      *
      * @param mixed $identifier
-     *
      * @psalm-param class-string<T> $documentName
+     *
      * @psalm-return T|(T&GhostObjectInterface<T>)
+     *
      * @template T of object
      */
     public function getReference(string $documentName, $identifier): object
@@ -655,9 +656,10 @@ public function getPartialReference(string $documentName, $identifier): object
      * @param mixed  $id
      * @param int    $lockMode
      * @param int    $lockVersion
-     *
      * @psalm-param class-string<T> $className
+     *
      * @psalm-return T|null
+     *
      * @template T of object
      */
     public function find($className, $id, $lockMode = LockMode::NONE, $lockVersion = null): ?object
diff --git a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
index 761f4dddd9..1987dbd87d 100644
--- a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php
@@ -446,10 +446,9 @@ public function hydrate(object \$document, array \$data, array \$hints = array()
      * Hydrate array of MongoDB document data into the given document object.
      *
      * @param array<string, mixed> $data
+     * @psalm-param Hints $hints Any hints to account for during reconstitution/lookup of the document.
      *
      * @return array<string, mixed>
-     *
-     * @psalm-param Hints $hints Any hints to account for during reconstitution/lookup of the document.
      */
     public function hydrate(object $document, array $data, array $hints = []): array
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
index b2625b6cb9..596cbd5f81 100644
--- a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
+++ b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
@@ -15,10 +15,9 @@ interface HydratorInterface
      * Hydrate array of MongoDB document data into the given document object.
      *
      * @param array<string, mixed> $data
+     * @psalm-param Hints $hints
      *
      * @return array<string, mixed>
-     *
-     * @psalm-param Hints $hints
      */
     public function hydrate(object $document, array $data, array $hints = []): array;
 }
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
index 6450028c84..e6855218c2 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
@@ -41,7 +41,6 @@ final class HydratingIterator implements Iterator
     /**
      * @param Traversable<mixed, TValue> $traversable
      * @param ClassMetadata<TDocument>   $class
-     *
      * @psalm-param Hints $unitOfWorkHints
      */
     public function __construct(Traversable $traversable, UnitOfWork $unitOfWork, ClassMetadata $class, array $unitOfWorkHints = [])
diff --git a/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php b/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
index 0471bdb14c..7695f5b4e0 100644
--- a/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
+++ b/lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php
@@ -341,7 +341,6 @@ public function loadMetadataForClass($className, \Doctrine\Persistence\Mapping\C
 
     /**
      * @param ClassMetadata<object> $class
-     *
      * @psalm-param FieldMappingConfig $mapping
      */
     private function addFieldMapping(ClassMetadata $class, array $mapping): void
diff --git a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
index 377ab98011..cee160dfe7 100644
--- a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
+++ b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php
@@ -92,9 +92,9 @@ public function setDirty($dirty);
      * Sets the collection's owning document together with the AssociationMapping that
      * describes the association between the owner and the elements of the collection.
      *
-     * @return void
-     *
      * @psalm-param FieldMapping $mapping
+     *
+     * @return void
      */
     public function setOwner(object $document, array $mapping);
 
@@ -154,17 +154,15 @@ public function getOwner(): ?object;
 
     /**
      * @return array
-     *
      * @psalm-return FieldMapping
      */
     public function getMapping();
 
     /**
      * @return ClassMetadata
+     * @psalm-return ClassMetadata<T>
      *
      * @throws MongoDBException
-     *
-     * @psalm-return ClassMetadata<T>
      */
     public function getTypeClass();
 
diff --git a/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php b/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
index f5af38d6c2..1fb4d0cd16 100644
--- a/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Proxy/Factory/ProxyFactory.php
@@ -19,9 +19,10 @@ public function generateProxyClasses(array $classes): int;
      * the given identifier.
      *
      * @param mixed $identifier
-     *
      * @psalm-param ClassMetadata<T> $metadata
+     *
      * @psalm-return T&GhostObjectInterface<T>
+     *
      * @template T of object
      */
     public function getProxy(ClassMetadata $metadata, $identifier): GhostObjectInterface;
diff --git a/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php b/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
index 2cea022bd0..910f539ce1 100644
--- a/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
+++ b/lib/Doctrine/ODM/MongoDB/Proxy/Resolver/ProxyManagerClassNameResolver.php
@@ -28,7 +28,9 @@ public function getRealClass(string $class): string
 
     /**
      * @psalm-param class-string<RealClassName>|class-string<ProxyInterface<RealClassName>> $className
+     *
      * @psalm-return class-string<RealClassName>
+     *
      * @psalm-template RealClassName of object
      */
     public function resolveClassName(string $className): string
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index 75ff2d94ec..e540a7d7e0 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
@@ -515,10 +515,10 @@ public function expr(): Expr
     /**
      * Specify $expr criteria for the current field.
      *
-     * @param array|Aggregation\Expr $expression
      * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
-     *
      * @see Aggregation\Expr::aggregationExpression()
+     *
+     * @param array|Aggregation\Expr $expression
      */
     public function aggregationExpression($expression): self
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php b/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
index 7bce208365..065ba26356 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/AbstractRepositoryFactory.php
@@ -27,7 +27,9 @@ abstract class AbstractRepositoryFactory implements RepositoryFactory
 
     /**
      * @psalm-param class-string<T> $documentName
+     *
      * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
+     *
      * @template T of object
      */
     public function getRepository(DocumentManager $documentManager, string $documentName): ObjectRepository
@@ -49,10 +51,11 @@ public function getRepository(DocumentManager $documentManager, string $document
     /**
      * Create a new repository instance for a document class.
      *
-     * @return DocumentRepository|GridFSRepository|ViewRepository
-     *
      * @psalm-param class-string<T> $documentName
+     *
+     * @return DocumentRepository|GridFSRepository|ViewRepository
      * @psalm-return DocumentRepository<T>|GridFSRepository<T>|ViewRepository<T>
+     *
      * @template T of object
      */
     protected function createRepository(DocumentManager $documentManager, string $documentName): ObjectRepository
@@ -101,10 +104,10 @@ protected function createRepository(DocumentManager $documentManager, string $do
      * Instantiates requested repository.
      *
      * @param ClassMetadata<T> $metadata
+     * @psalm-param class-string<T> $repositoryClassName
      *
      * @return ObjectRepository<T>
      *
-     * @psalm-param class-string<T> $repositoryClassName
      * @template T of object
      */
     abstract protected function instantiateRepository(string $repositoryClassName, DocumentManager $documentManager, ClassMetadata $metadata): ObjectRepository;
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php b/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
index 2b767e02d6..5305f896d2 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php
@@ -61,7 +61,6 @@ class DocumentRepository implements ObjectRepository, Selectable
      * @param DocumentManager $dm            The DocumentManager to use.
      * @param UnitOfWork      $uow           The UnitOfWork to use.
      * @param ClassMetadata   $classMetadata The class metadata.
-     *
      * @psalm-param ClassMetadata<T>   $classMetadata The class metadata.
      */
     public function __construct(DocumentManager $dm, UnitOfWork $uow, ClassMetadata $classMetadata)
@@ -102,10 +101,10 @@ public function clear(): void
      *
      * @param mixed $id Identifier.
      *
+     * @psalm-return T|null
+     *
      * @throws MappingException
      * @throws LockException
-     *
-     * @psalm-return T|null
      */
     public function find($id, int $lockMode = LockMode::NONE, ?int $lockVersion = null): ?object
     {
@@ -182,7 +181,6 @@ public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $
      * @param array<string, mixed>      $criteria
      *
      * @return object|null The object.
-     *
      * @psalm-return T|null
      */
     public function findOneBy(array $criteria, ?array $sort = null): ?object
diff --git a/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php b/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
index ca92e2caea..ee5e681ffa 100644
--- a/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
+++ b/lib/Doctrine/ODM/MongoDB/Repository/RepositoryFactory.php
@@ -16,7 +16,9 @@ interface RepositoryFactory
      * Gets the repository for a document class.
      *
      * @psalm-param class-string<T> $documentName
+     *
      * @psalm-return ObjectRepository<T>
+     *
      * @template T of object
      */
     public function getRepository(DocumentManager $documentManager, string $documentName): ObjectRepository;
diff --git a/lib/Doctrine/ODM/MongoDB/SchemaManager.php b/lib/Doctrine/ODM/MongoDB/SchemaManager.php
index bf00a15944..64bcbfdf70 100644
--- a/lib/Doctrine/ODM/MongoDB/SchemaManager.php
+++ b/lib/Doctrine/ODM/MongoDB/SchemaManager.php
@@ -104,9 +104,9 @@ public function updateIndexes(?int $maxTimeMs = null, ?WriteConcern $writeConcer
      * Indexes that exist in MongoDB but not the document metadata will be
      * deleted.
      *
-     * @throws InvalidArgumentException
-     *
      * @psalm-param class-string $documentName
+     *
+     * @throws InvalidArgumentException
      */
     public function updateDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -152,6 +152,7 @@ public function updateDocumentIndexes(string $documentName, ?int $maxTimeMs = nu
 
     /**
      * @psalm-param class-string $documentName
+     *
      * @psalm-return IndexMapping[]
      */
     public function getDocumentIndexes(string $documentName): array
@@ -164,6 +165,7 @@ public function getDocumentIndexes(string $documentName): array
     /**
      * @psalm-param class-string $documentName
      * @psalm-param array<class-string, bool> $visited
+     *
      * @psalm-return IndexMapping[]
      */
     private function doGetDocumentIndexes(string $documentName, array &$visited): array
@@ -265,9 +267,9 @@ private function prepareIndexes(ClassMetadata $class): array
     /**
      * Ensure the given document's indexes are created.
      *
-     * @throws InvalidArgumentException
-     *
      * @psalm-param class-string $documentName
+     *
+     * @throws InvalidArgumentException
      */
     public function ensureDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null, bool $background = false): void
     {
@@ -310,9 +312,9 @@ public function deleteIndexes(?int $maxTimeMs = null, ?WriteConcern $writeConcer
     /**
      * Delete the given document's indexes.
      *
-     * @throws InvalidArgumentException
-     *
      * @psalm-param class-string $documentName
+     *
+     * @throws InvalidArgumentException
      */
     public function deleteDocumentIndexes(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -412,9 +414,9 @@ public function createCollections(?int $maxTimeMs = null, ?WriteConcern $writeCo
     /**
      * Create the document collection for a mapped class.
      *
-     * @throws InvalidArgumentException
-     *
      * @psalm-param class-string $documentName
+     *
+     * @throws InvalidArgumentException
      */
     public function createDocumentCollection(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -491,9 +493,9 @@ public function dropCollections(?int $maxTimeMs = null, ?WriteConcern $writeConc
     /**
      * Drop the document collection for a mapped class.
      *
-     * @throws InvalidArgumentException
-     *
      * @psalm-param class-string $documentName
+     *
+     * @throws InvalidArgumentException
      */
     public function dropDocumentCollection(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -531,9 +533,9 @@ public function dropDatabases(?int $maxTimeMs = null, ?WriteConcern $writeConcer
     /**
      * Drop the document database for a mapped class.
      *
-     * @throws InvalidArgumentException
-     *
      * @psalm-param class-string $documentName
+     *
+     * @throws InvalidArgumentException
      */
     public function dropDocumentDatabase(string $documentName, ?int $maxTimeMs = null, ?WriteConcern $writeConcern = null): void
     {
@@ -753,9 +755,9 @@ public function ensureSharding(?WriteConcern $writeConcern = null): void
     /**
      * Ensure sharding for collection by document name.
      *
-     * @throws MongoDBException
-     *
      * @psalm-param class-string $documentName
+     *
+     * @throws MongoDBException
      */
     public function ensureDocumentSharding(string $documentName, ?WriteConcern $writeConcern = null): void
     {
@@ -780,9 +782,9 @@ public function ensureDocumentSharding(string $documentName, ?WriteConcern $writ
     /**
      * Enable sharding for database which contains documents with given name.
      *
-     * @throws MongoDBException
-     *
      * @psalm-param class-string $documentName
+     *
+     * @throws MongoDBException
      */
     public function enableShardingForDbByDocumentName(string $documentName): void
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php b/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
index f70cb41e9c..31bb5affd9 100644
--- a/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
+++ b/lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php
@@ -90,7 +90,6 @@ public function loadClassMetadata(LoadClassMetadataEventArgs $args): void
 
     /**
      * @param ClassMetadata<object> $classMetadata
-     *
      * @psalm-param AssociationFieldMapping $mapping
      */
     private function remapAssociation(ClassMetadata $classMetadata, array $mapping): void
diff --git a/lib/Doctrine/ODM/MongoDB/Types/Type.php b/lib/Doctrine/ODM/MongoDB/Types/Type.php
index 123f2f4f37..d6f2b4636d 100644
--- a/lib/Doctrine/ODM/MongoDB/Types/Type.php
+++ b/lib/Doctrine/ODM/MongoDB/Types/Type.php
@@ -200,9 +200,10 @@ public static function convertPHPToDatabaseValue($value)
     /**
      * Adds a custom type to the type map.
      *
+     * @psalm-param class-string $className
+     *
      * @throws MappingException
      *
-     * @psalm-param class-string $className
      * @static
      */
     public static function addType(string $name, string $className): void
@@ -227,9 +228,10 @@ public static function hasType(string $name): bool
     /**
      * Overrides an already defined type to use a different implementation.
      *
+     * @psalm-param class-string $className
+     *
      * @throws MappingException
      *
-     * @psalm-param class-string $className
      * @static
      */
     public static function overrideType(string $name, string $className): void
diff --git a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
index 3030102ab9..581f6a877b 100644
--- a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
+++ b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
@@ -331,7 +331,9 @@ public function getParentAssociation(object $document): ?array
      * Get the document persister instance for the given document name
      *
      * @psalm-param class-string<T> $documentName
+     *
      * @psalm-return Persisters\DocumentPersister<T>
+     *
      * @template T of object
      */
     public function getDocumentPersister(string $documentName): Persisters\DocumentPersister
@@ -386,7 +388,6 @@ public function setDocumentPersister(string $documentName, Persisters\DocumentPe
      * 3) All document deletions
      *
      * @param array $options Array of options to be used with batchInsert(), update() and remove()
-     *
      * @psalm-param CommitOptions $options
      */
     public function commit(array $options = []): void
@@ -548,7 +549,6 @@ private function computeScheduleUpsertsChangeSets(): void
      * Gets the changeset for a document.
      *
      * @return array array('property' => array(0 => mixed, 1 => mixed))
-     *
      * @psalm-return array<string, ChangeSet>
      */
     public function getDocumentChangeSet(object $document): array
@@ -635,6 +635,7 @@ public function getDocumentActualData(object $document): array
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
+     *
      * @template T of object
      */
     public function computeChangeSet(ClassMetadata $class, object $document): void
@@ -656,6 +657,7 @@ public function computeChangeSet(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
+     *
      * @template T of object
      */
     private function computeOrRecomputeChangeSet(ClassMetadata $class, object $document, bool $recompute = false): void
@@ -926,10 +928,9 @@ public function computeChangeSets(): void
      * Computes the changes of an association.
      *
      * @param mixed $value The value of the association.
+     * @psalm-param AssociationFieldMapping $assoc
      *
      * @throws InvalidArgumentException
-     *
-     * @psalm-param AssociationFieldMapping $assoc
      */
     private function computeAssociationChanges(object $parentDocument, array $assoc, $value): void
     {
@@ -1049,10 +1050,11 @@ private function computeAssociationChanges(object $parentDocument, array $assoc,
      * because this method is invoked during a commit cycle then the change sets are added.
      * whereby changes detected in this method prevail.
      *
-     * @throws InvalidArgumentException If the passed document is not MANAGED.
-     *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
+     *
+     * @throws InvalidArgumentException If the passed document is not MANAGED.
+     *
      * @template T of object
      */
     public function recomputeSingleDocumentChangeSet(ClassMetadata $class, object $document): void
@@ -1076,10 +1078,11 @@ public function recomputeSingleDocumentChangeSet(ClassMetadata $class, object $d
     }
 
     /**
-     * @throws InvalidArgumentException If there is something wrong with document's identifier.
-     *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
+     *
+     * @throws InvalidArgumentException If there is something wrong with document's identifier.
+     *
      * @template T of object
      */
     private function persistNew(ClassMetadata $class, object $document): void
@@ -1132,6 +1135,7 @@ private function persistNew(ClassMetadata $class, object $document): void
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
+     *
      * @template T of object
      */
     private function executeInserts(ClassMetadata $class, array $documents, array $options = []): void
@@ -1156,6 +1160,7 @@ private function executeInserts(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
+     *
      * @template T of object
      */
     private function executeUpserts(ClassMetadata $class, array $documents, array $options = []): void
@@ -1180,6 +1185,7 @@ private function executeUpserts(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
+     *
      * @template T of object
      */
     private function executeUpdates(ClassMetadata $class, array $documents, array $options = []): void
@@ -1210,6 +1216,7 @@ private function executeUpdates(ClassMetadata $class, array $documents, array $o
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T[] $documents
      * @psalm-param CommitOptions $options
+     *
      * @template T of object
      */
     private function executeDeletions(ClassMetadata $class, array $documents, array $options = []): void
@@ -1257,10 +1264,11 @@ private function executeDeletions(ClassMetadata $class, array $documents, array
      *
      * @internal
      *
-     * @throws InvalidArgumentException
-     *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
+     *
+     * @throws InvalidArgumentException
+     *
      * @template T of object
      */
     public function scheduleForInsert(ClassMetadata $class, object $document): void
@@ -1294,10 +1302,11 @@ public function scheduleForInsert(ClassMetadata $class, object $document): void
      *
      * @internal
      *
-     * @throws InvalidArgumentException
-     *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
+     *
+     * @throws InvalidArgumentException
+     *
      * @template T of object
      */
     public function scheduleForUpsert(ClassMetadata $class, object $document): void
@@ -1584,11 +1593,12 @@ public function removeFromIdentityMap(object $document): bool
      * @internal
      *
      * @param mixed $id Document identifier
+     * @psalm-param ClassMetadata<T> $class
+     *
+     * @psalm-return T
      *
      * @throws InvalidArgumentException If the class does not have an identifier.
      *
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-return T
      * @template T of object
      * @psalm-suppress InvalidReturnStatement, InvalidReturnType because of the inability of defining a generic property map
      */
@@ -1610,13 +1620,13 @@ public function getById($id, ClassMetadata $class): object
      * @internal
      *
      * @param mixed $id Document identifier
+     * @psalm-param ClassMetadata<T> $class
      *
      * @return mixed The found document or FALSE.
+     * @psalm-return T|false
      *
      * @throws InvalidArgumentException If the class does not have an identifier.
      *
-     * @psalm-param ClassMetadata<T> $class
-     * @psalm-return T|false
      * @template T of object
      * @psalm-suppress InvalidReturnStatement, InvalidReturnType because of the inability of defining a generic property map
      */
@@ -1841,13 +1851,12 @@ public function merge(object $document): object
      * Executes a merge operation on a document.
      *
      * @param array<string, object> $visited
+     * @psalm-param AssociationFieldMapping|null $assoc
      *
      * @throws InvalidArgumentException If the entity instance is NEW.
      * @throws LockException If the document uses optimistic locking through a
      *                       version attribute and the version check against the
      *                       managed copy fails.
-     *
-     * @psalm-param AssociationFieldMapping|null $assoc
      */
     private function doMerge(object $document, array &$visited, ?object $prevManagedCopy = null, ?array $assoc = null): object
     {
@@ -2433,7 +2442,9 @@ public function unscheduleOrphanRemoval(object $document): void
      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
      * @psalm-param T $document
      * @psalm-param ClassMetadata<T> $class
+     *
      * @psalm-return PersistentCollectionInterface<array-key, object>
+     *
      * @template T of object
      */
     private function fixPersistentCollectionOwnership(PersistentCollectionInterface $coll, object $document, ClassMetadata $class, string $propName): PersistentCollectionInterface
@@ -2582,7 +2593,6 @@ public function isCollectionScheduledForUpdate(PersistentCollectionInterface $co
      * @internal
      *
      * @return PersistentCollectionInterface[]
-     *
      * @psalm-return array<PersistentCollectionInterface<array-key, object>>
      */
     public function getVisitedCollections(object $document): array
@@ -2598,7 +2608,6 @@ public function getVisitedCollections(object $document): array
      * @internal
      *
      * @return PersistentCollectionInterface[]
-     *
      * @psalm-return array<string, PersistentCollectionInterface<array-key, object>>
      */
     public function getScheduledCollections(object $document): array
@@ -2739,7 +2748,9 @@ public function getClassNameForAssociation(array $mapping, $data): string
      * @psalm-param array<string, mixed> $data
      * @psalm-param T|null $document
      * @psalm-param Hints $hints
+     *
      * @psalm-return T
+     *
      * @template T of object
      */
     public function getOrCreateDocument(string $className, array $data, array &$hints = [], ?object $document = null): object
diff --git a/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php b/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
index ff632f15de..a2a70ca5e3 100644
--- a/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
+++ b/lib/Doctrine/ODM/MongoDB/Utility/LifecycleEventManager.php
@@ -65,6 +65,7 @@ public function postCollectionLoad(PersistentCollectionInterface $coll): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
+     *
      * @template T of object
      */
     public function postPersist(ClassMetadata $class, object $document): void
@@ -79,6 +80,7 @@ public function postPersist(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
+     *
      * @template T of object
      */
     public function postRemove(ClassMetadata $class, object $document): void
@@ -93,6 +95,7 @@ public function postRemove(ClassMetadata $class, object $document): void
      *
      * @psalm-param ClassMetadata<T> $class
      * @psalm-param T $document
+     *
      * @template T of object
      */
     public function postUpdate(ClassMetadata $class, object $document): void
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php b/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php
index 494525a7e4..5783c7e9ed 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/ClassMetadataTestUtil.php
@@ -15,6 +15,7 @@ class ClassMetadataTestUtil
 {
     /**
      * @psalm-param FieldMappingConfig $mapping
+     *
      * @psalm-return FieldMapping
      */
     public static function getFieldMapping(array $mapping): array
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php b/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php
index 55163071ba..20ae2fe767 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php
@@ -645,8 +645,8 @@ public static function dataProviderTestWriteConcern(): array
 
     /**
      * @param int|string $writeConcern
-     *
      * @psalm-param class-string $class
+     *
      * @dataProvider dataProviderTestWriteConcern
      */
     public function testExecuteInsertsRespectsWriteConcern(string $class, $writeConcern): void
@@ -669,8 +669,8 @@ public function testExecuteInsertsRespectsWriteConcern(string $class, $writeConc
 
     /**
      * @param int|string $writeConcern
-     *
      * @psalm-param class-string $class
+     *
      * @dataProvider dataProviderTestWriteConcern
      */
     public function testExecuteUpsertsRespectsWriteConcern(string $class, $writeConcern): void
@@ -694,8 +694,8 @@ public function testExecuteUpsertsRespectsWriteConcern(string $class, $writeConc
 
     /**
      * @param int|string $writeConcern
-     *
      * @psalm-param class-string $class
+     *
      * @dataProvider dataProviderTestWriteConcern
      */
     public function testRemoveRespectsWriteConcern(string $class, $writeConcern): void

From a28c84c3a144eb6316304a5e752f0fb72df15e73 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@outlook.com>
Date: Fri, 4 Nov 2022 19:18:23 +0100
Subject: [PATCH 28/31] + minors fixes for vendor/bin/phpstan validation

---
 composer.json                                                  | 2 +-
 lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php          | 1 +
 lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php        | 2 ++
 lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php          | 1 +
 lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php        | 1 +
 lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php     | 1 +
 .../MongoDB/PersistentCollection/PersistentCollectionTrait.php | 2 ++
 lib/Doctrine/ODM/MongoDB/UnitOfWork.php                        | 3 ++-
 .../ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php         | 1 +
 9 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/composer.json b/composer.json
index cca67149b5..4cc7926a8e 100644
--- a/composer.json
+++ b/composer.json
@@ -22,7 +22,7 @@
         { "name": "Andreas Braun", "email": "alcaeus@alcaeus.org" }
     ],
     "require": {
-        "php": "^7.4 || ^8.0",
+        "php": "^8.1",
         "ext-mongodb": "^1.5",
         "doctrine/annotations": "^1.12",
         "doctrine/cache": "^1.11 || ^2.0",
diff --git a/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php b/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
index 4a1a8e13a3..85a94ec5bf 100644
--- a/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
+++ b/lib/Doctrine/ODM/MongoDB/Event/PreUpdateEventArgs.php
@@ -5,6 +5,7 @@
 namespace Doctrine\ODM\MongoDB\Event;
 
 use Doctrine\ODM\MongoDB\DocumentManager;
+use Doctrine\ODM\MongoDB\UnitOfWork;
 use InvalidArgumentException;
 
 use function get_class;
diff --git a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
index 596cbd5f81..58fc21c07b 100644
--- a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
+++ b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorInterface.php
@@ -4,6 +4,8 @@
 
 namespace Doctrine\ODM\MongoDB\Hydrator;
 
+use Doctrine\ODM\MongoDB\UnitOfWork;
+
 /**
  * The HydratorInterface defines methods all hydrator need to implement
  *
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
index 257c6acd12..5f8867dc7f 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
@@ -8,6 +8,7 @@
 use Generator;
 use RuntimeException;
 use Traversable;
+use ReturnTypeWillChange;
 
 use function count;
 use function current;
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
index e6855218c2..7309e4a6a8 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
@@ -10,6 +10,7 @@
 use Iterator;
 use RuntimeException;
 use Traversable;
+use ReturnTypeWillChange;
 
 /**
  * Iterator that wraps a traversable and hydrates results into objects
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
index c838203f14..981981e57f 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
@@ -8,6 +8,7 @@
 use LogicException;
 use RuntimeException;
 use Traversable;
+use ReturnTypeWillChange;
 
 use function iterator_to_array;
 use function sprintf;
diff --git a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
index 56ee2824fc..94bcbbedfe 100644
--- a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
+++ b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
@@ -8,10 +8,12 @@
 use Closure;
 use Doctrine\Common\Collections\Collection as BaseCollection;
 use Doctrine\ODM\MongoDB\DocumentManager;
+use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\MongoDBException;
 use Doctrine\ODM\MongoDB\UnitOfWork;
 use Doctrine\ODM\MongoDB\Utility\CollectionHelper;
 use Traversable;
+use ReturnTypeWillChange;
 
 use function array_combine;
 use function array_diff_key;
diff --git a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
index 581f6a877b..6b2ee9706e 100644
--- a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
+++ b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
@@ -25,6 +25,7 @@
 use Doctrine\Persistence\PropertyChangedListener;
 use InvalidArgumentException;
 use MongoDB\BSON\UTCDateTime;
+use MongoDB\Driver\WriteConcern;
 use ProxyManager\Proxy\GhostObjectInterface;
 use ReflectionProperty;
 use UnexpectedValueException;
@@ -54,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,
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php
index cbbaf39b50..84e8625469 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1152Test.php
@@ -7,6 +7,7 @@
 use Doctrine\ODM\MongoDB\Event\LifecycleEventArgs;
 use Doctrine\ODM\MongoDB\Events;
 use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\Tests\BaseTest;
 
 class GH1152Test extends BaseTest

From 771b43df9f3ee57fe3aa6f82fa95bb24095fb9a0 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@outlook.com>
Date: Sat, 5 Nov 2022 02:29:16 +0100
Subject: [PATCH 29/31] + rollback some unexpected changes in previous commits

---
 composer.json                                       |  2 +-
 lib/Doctrine/ODM/MongoDB/Configuration.php          |  3 ++-
 .../ODM/MongoDB/Iterator/CachingIterator.php        |  5 ++---
 .../ODM/MongoDB/Iterator/HydratingIterator.php      |  5 ++---
 .../ODM/MongoDB/Iterator/PrimingIterator.php        |  5 ++---
 .../ODM/MongoDB/Iterator/UnrewindableIterator.php   |  5 ++---
 .../PersistentCollectionTrait.php                   | 13 ++++++-------
 7 files changed, 17 insertions(+), 21 deletions(-)

diff --git a/composer.json b/composer.json
index 4cc7926a8e..cca67149b5 100644
--- a/composer.json
+++ b/composer.json
@@ -22,7 +22,7 @@
         { "name": "Andreas Braun", "email": "alcaeus@alcaeus.org" }
     ],
     "require": {
-        "php": "^8.1",
+        "php": "^7.4 || ^8.0",
         "ext-mongodb": "^1.5",
         "doctrine/annotations": "^1.12",
         "doctrine/cache": "^1.11 || ^2.0",
diff --git a/lib/Doctrine/ODM/MongoDB/Configuration.php b/lib/Doctrine/ODM/MongoDB/Configuration.php
index de421104bf..6cc439a6c4 100644
--- a/lib/Doctrine/ODM/MongoDB/Configuration.php
+++ b/lib/Doctrine/ODM/MongoDB/Configuration.php
@@ -104,7 +104,8 @@ class Configuration
      *      persistentCollectionGenerator?: PersistentCollectionGenerator,
      *      persistentCollectionDir?: string,
      *      persistentCollectionNamespace?: string,
-     *      repositoryFactory?: RepositoryFactory
+     *      repositoryFactory?: RepositoryFactory,
+     *      writeConcern?: WriteConcern
      * }
      */
     private array $attributes = [];
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
index 5f8867dc7f..8c134c15db 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/CachingIterator.php
@@ -8,7 +8,6 @@
 use Generator;
 use RuntimeException;
 use Traversable;
-use ReturnTypeWillChange;
 
 use function count;
 use function current;
@@ -80,7 +79,7 @@ public function toArray(): array
     /**
      * @return TValue|false
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function current()
     {
         return current($this->items);
@@ -89,7 +88,7 @@ public function current()
     /**
      * @return mixed
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function key()
     {
         return key($this->items);
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
index 7309e4a6a8..dcfb27d023 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/HydratingIterator.php
@@ -10,7 +10,6 @@
 use Iterator;
 use RuntimeException;
 use Traversable;
-use ReturnTypeWillChange;
 
 /**
  * Iterator that wraps a traversable and hydrates results into objects
@@ -60,7 +59,7 @@ public function __destruct()
     /**
      * @return TDocument|null
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function current()
     {
         return $this->hydrate($this->getIterator()->current());
@@ -69,7 +68,7 @@ public function current()
     /**
      * @return mixed
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function key()
     {
         return $this->getIterator()->key();
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/PrimingIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/PrimingIterator.php
index cedb8898ef..dd954256a4 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/PrimingIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/PrimingIterator.php
@@ -7,7 +7,6 @@
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\Query\ReferencePrimer;
 use Doctrine\ODM\MongoDB\UnitOfWork;
-use ReturnTypeWillChange;
 
 use function is_callable;
 use function iterator_to_array;
@@ -62,7 +61,7 @@ public function toArray(): array
     /**
      * @return TValue|null
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function current()
     {
         $this->primeReferences();
@@ -78,7 +77,7 @@ public function next(): void
     /**
      * @return mixed
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function key()
     {
         return $this->iterator->key();
diff --git a/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php b/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
index 981981e57f..6883c960cb 100644
--- a/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
+++ b/lib/Doctrine/ODM/MongoDB/Iterator/UnrewindableIterator.php
@@ -8,7 +8,6 @@
 use LogicException;
 use RuntimeException;
 use Traversable;
-use ReturnTypeWillChange;
 
 use function iterator_to_array;
 use function sprintf;
@@ -61,7 +60,7 @@ public function toArray(): array
     /**
      * @return TValue|null
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function current()
     {
         return $this->getIterator()->current();
@@ -70,7 +69,7 @@ public function current()
     /**
      * @return mixed
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function key()
     {
         if ($this->iterator) {
diff --git a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
index 94bcbbedfe..42549aab18 100644
--- a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
+++ b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionTrait.php
@@ -13,7 +13,6 @@
 use Doctrine\ODM\MongoDB\UnitOfWork;
 use Doctrine\ODM\MongoDB\Utility\CollectionHelper;
 use Traversable;
-use ReturnTypeWillChange;
 
 use function array_combine;
 use function array_diff_key;
@@ -410,7 +409,7 @@ public function getValues()
     /**
      * @return int
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function count()
     {
         // Workaround around not being able to directly count inverse collections anymore
@@ -438,7 +437,7 @@ public function isEmpty()
      * @return Traversable
      * @psalm-return Traversable<TKey, T>
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function getIterator()
     {
         $this->initialize();
@@ -537,7 +536,7 @@ public function __sleep()
      *
      * @return bool
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function offsetExists($offset)
     {
         $this->initialize();
@@ -551,7 +550,7 @@ public function offsetExists($offset)
      * @return mixed
      * @psalm-return T|null
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function offsetGet($offset)
     {
         $this->initialize();
@@ -565,7 +564,7 @@ public function offsetGet($offset)
      *
      * @return void
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function offsetSet($offset, $value)
     {
         if (! isset($offset)) {
@@ -582,7 +581,7 @@ public function offsetSet($offset, $value)
      *
      * @return void
      */
-    #[ReturnTypeWillChange]
+    #[\ReturnTypeWillChange]
     public function offsetUnset($offset)
     {
         $this->doRemove($offset, true);

From eb60a6f4ef8ca122a05b0fcd471e4cb539171666 Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@outlook.com>
Date: Sun, 6 Nov 2022 16:55:45 +0100
Subject: [PATCH 30/31] + replaced Query\Builder::expr() calls to
 Query\Builder::createQueryExpression() + replaced Aggregation\Builder::expr()
 calls to Aggregation\Builder::createAggregationExpression() + minor psalm
 docblock update

---
 .../Stage/Bucket/AbstractOutput.php            |  2 +-
 .../ODM/MongoDB/Aggregation/Stage/Group.php    |  2 +-
 .../MongoDB/Aggregation/Stage/MatchStage.php   |  2 +-
 .../ODM/MongoDB/Aggregation/Stage/Operator.php |  2 +-
 lib/Doctrine/ODM/MongoDB/Query/Builder.php     | 17 +++++++++++------
 .../MongoDB/Query/QueryExpressionVisitor.php   |  6 +++---
 .../ODM/MongoDB/Types/DateImmutableType.php    |  2 ++
 .../MongoDB/Tests/Aggregation/BuilderTest.php  | 14 +++++++-------
 .../Tests/Aggregation/Stage/RedactTest.php     |  4 ++--
 .../Aggregation/Stage/ReplaceRootTest.php      |  2 +-
 .../ODM/MongoDB/Tests/Functional/QueryTest.php |  9 +++++----
 .../Tests/Functional/Ticket/GH1674Test.php     |  2 +-
 .../Tests/Functional/Ticket/GH2251Test.php     |  4 ++--
 .../Tests/Functional/Ticket/GH596Test.php      |  4 ++--
 .../ODM/MongoDB/Tests/Query/BuilderTest.php    | 18 +++++++++---------
 .../ODM/MongoDB/Tests/Query/ExprTest.php       |  4 ++--
 tests/Doctrine/ODM/MongoDB/Tests/QueryTest.php |  6 +++---
 17 files changed, 54 insertions(+), 46 deletions(-)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Bucket/AbstractOutput.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Bucket/AbstractOutput.php
index 89cde5600b..feb48089ec 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Bucket/AbstractOutput.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Bucket/AbstractOutput.php
@@ -25,7 +25,7 @@ public function __construct(Builder $builder, Stage\AbstractBucket $bucket)
         parent::__construct($builder);
 
         $this->bucket = $bucket;
-        $this->expr   = $builder->expr();
+        $this->expr   = $builder->createAggregationExpression();
     }
 
     public function getExpression(): array
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Group.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Group.php
index 88bb883dbe..332c79e598 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Group.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Group.php
@@ -19,7 +19,7 @@ public function __construct(Builder $builder)
     {
         parent::__construct($builder);
 
-        $this->expr = $builder->expr();
+        $this->expr = $builder->createAggregationExpression();
     }
 
     public function getExpression(): array
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
index aa862c3d80..73cc19eb4d 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/MatchStage.php
@@ -25,7 +25,7 @@ public function __construct(Builder $builder)
     {
         parent::__construct($builder);
 
-        $this->query = $this->expr();
+        $this->query = $this->createQueryExpression();
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Operator.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Operator.php
index 2f2c8fd1d1..ede563aa58 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Operator.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Operator.php
@@ -27,7 +27,7 @@ public function __construct(Builder $builder)
     {
         parent::__construct($builder);
 
-        $this->expr = $builder->expr();
+        $this->expr = $builder->createAggregationExpression();
     }
 
     /**
diff --git a/lib/Doctrine/ODM/MongoDB/Query/Builder.php b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
index e540a7d7e0..386937c73d 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/Builder.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/Builder.php
@@ -122,7 +122,7 @@ public function __clone()
     /**
      * Add one or more $and clauses to the current query.
      *
-     * You can create a new expression using the {@link Builder::expr()} method.
+     * You can create a new expression using the {@link Builder::createAggregationExpression()} method.
      *
      * @see Expr::addAnd()
      * @see https://docs.mongodb.com/manual/reference/operator/and/
@@ -140,7 +140,7 @@ public function addAnd($expression, ...$expressions): self
     /**
      * Add one or more $nor clauses to the current query.
      *
-     * You can create a new expression using the {@link Builder::expr()} method.
+     * You can create a new expression using the {@link Builder::createAggregationExpression()} method.
      *
      * @see Expr::addNor()
      * @see https://docs.mongodb.com/manual/reference/operator/nor/
@@ -158,7 +158,7 @@ public function addNor($expression, ...$expressions): self
     /**
      * Add one or more $or clauses to the current query.
      *
-     * You can create a new expression using the {@link Builder::expr()} method.
+     * You can create a new expression using the {@link Builder::createAggregationExpression()} method.
      *
      * @see Expr::addOr()
      * @see https://docs.mongodb.com/manual/reference/operator/or/
@@ -430,7 +430,7 @@ public function distinct(string $field): self
     /**
      * Specify $elemMatch criteria for the current field.
      *
-     * You can create a new expression using the {@link Builder::expr()} method.
+     * You can create a new expression using the {@link Builder::createAggregationExpression()} method.
      *
      * @see Expr::elemMatch()
      * @see https://docs.mongodb.com/manual/reference/operator/elemMatch/
@@ -465,6 +465,9 @@ public function equals($value): self
      * excluded.
      *
      * @param string[]|string $fieldName,...
+     * @param null|string|string[] $fieldName
+     *
+     * @psalm-param 'comments'|array{0: 'name', 1: 'issues'}|null $fieldName
      */
     public function exclude($fieldName = null): self
     {
@@ -1054,7 +1057,7 @@ public function nearSphere($x, $y = null): self
     /**
      * Negates an expression for the current field.
      *
-     * You can create a new expression using the {@link Builder::expr()} method.
+     * You can create a new expression using the {@link Builder::createAggregationExpression()} method.
      *
      * @see Expr::not()
      * @see https://docs.mongodb.com/manual/reference/operator/not/
@@ -1288,7 +1291,9 @@ public function returnNew(bool $bool = true): self
     /**
      * Set one or more fields to be included in the query projection.
      *
-     * @param string[]|string $fieldName,...
+     * @param null|string|string[] $fieldName
+     *
+     * @return Builder
      */
     public function select($fieldName = null): self
     {
diff --git a/lib/Doctrine/ODM/MongoDB/Query/QueryExpressionVisitor.php b/lib/Doctrine/ODM/MongoDB/Query/QueryExpressionVisitor.php
index e9fe6f1d7a..a652ebdf7b 100644
--- a/lib/Doctrine/ODM/MongoDB/Query/QueryExpressionVisitor.php
+++ b/lib/Doctrine/ODM/MongoDB/Query/QueryExpressionVisitor.php
@@ -71,14 +71,14 @@ public function walkComparison(Comparison $comparison): Expr
             case Comparison::NIN:
                 $method = self::$operatorMethods[$comparison->getOperator()];
 
-                return $this->builder->expr()
+                return $this->builder->createQueryExpression()
                     ->field($comparison->getField())
                     ->{$method}($this->walkValue($comparison->getValue()));
 
             case Comparison::CONTAINS:
                 $value = $this->walkValue($comparison->getValue());
 
-                return $this->builder->expr()
+                return $this->builder->createQueryExpression()
                     ->field($comparison->getField())
                     ->equals(new Regex($value, ''));
 
@@ -99,7 +99,7 @@ public function walkCompositeExpression(CompositeExpression $expr): Expr
         }
 
         $method     = self::$compositeMethods[$expr->getType()];
-        $outputExpr = $this->builder->expr();
+        $outputExpr = $this->builder->createQueryExpression();
 
         foreach ($expr->getExpressionList() as $child) {
             $outputExpr->{$method}($this->dispatch($child));
diff --git a/lib/Doctrine/ODM/MongoDB/Types/DateImmutableType.php b/lib/Doctrine/ODM/MongoDB/Types/DateImmutableType.php
index edaac74042..96fde2023d 100644
--- a/lib/Doctrine/ODM/MongoDB/Types/DateImmutableType.php
+++ b/lib/Doctrine/ODM/MongoDB/Types/DateImmutableType.php
@@ -16,6 +16,8 @@ class DateImmutableType extends DateType
 {
     /**
      * @return DateTimeImmutable
+     *
+     * @param \MongoDB\BSON\UTCDateTime|float $value
      */
     public static function getDateTime($value): DateTimeInterface
     {
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/BuilderTest.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/BuilderTest.php
index 1a8e1e1e14..0d1ecc40ad 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/BuilderTest.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/BuilderTest.php
@@ -135,7 +135,7 @@ public function testGetPipeline(): void
             ->unwind('b')
             ->redact()
                 ->cond(
-                    $builder->expr()->lte('$accessLevel', 3),
+                    $builder->createAggregationExpression()->lte('$accessLevel', 3),
                     '$$KEEP',
                     '$$REDACT'
                 )
@@ -144,9 +144,9 @@ public function testGetPipeline(): void
                 ->includeFields(['user', 'amount', 'invoiceAddress'])
                 ->field('deliveryAddress')
                 ->cond(
-                    $builder->expr()
-                        ->addAnd($builder->expr()->eq('$useAlternateDeliveryAddress', true))
-                        ->addAnd($builder->expr()->ne('$deliveryAddress', null)),
+                    $builder->createAggregationExpression()
+                        ->addAnd($builder->createAggregationExpression()->eq('$useAlternateDeliveryAddress', true))
+                        ->addAnd($builder->createAggregationExpression()->ne('$deliveryAddress', null)),
                     '$deliveryAddress',
                     '$invoiceAddress'
                 )
@@ -157,7 +157,7 @@ public function testGetPipeline(): void
                 ->sum(1)
                 ->field('amount')
                 ->expression(
-                    $builder->expr()
+                    $builder->createAggregationExpression()
                         ->field('total')
                         ->sum('$amount')
                         ->field('avg')
@@ -267,9 +267,9 @@ public function testPipelineConvertsTypes(): void
             ->group()
                 ->field('id')
                 ->expression(
-                    $builder->expr()
+                    $builder->createAggregationExpression()
                         ->cond(
-                            $builder->expr()->lt('$createdAt', $dateTime),
+                            $builder->createAggregationExpression()->lt('$createdAt', $dateTime),
                             true,
                             false
                         )
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/Stage/RedactTest.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/Stage/RedactTest.php
index 6f3e5a22dd..ab715d9c85 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/Stage/RedactTest.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/Stage/RedactTest.php
@@ -19,7 +19,7 @@ public function testRedactStage(): void
         $redactStage = new Redact($builder);
         $redactStage
             ->cond(
-                $builder->expr()->lte('$accessLevel', 3),
+                $builder->createAggregationExpression()->lte('$accessLevel', 3),
                 '$$KEEP',
                 '$$REDACT'
             );
@@ -33,7 +33,7 @@ public function testRedactFromBuilder(): void
         $builder
             ->redact()
             ->cond(
-                $builder->expr()->lte('$accessLevel', 3),
+                $builder->createAggregationExpression()->lte('$accessLevel', 3),
                 '$$KEEP',
                 '$$REDACT'
             );
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/Stage/ReplaceRootTest.php b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/Stage/ReplaceRootTest.php
index 84cd7884ea..aad032e638 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/Stage/ReplaceRootTest.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Aggregation/Stage/ReplaceRootTest.php
@@ -43,7 +43,7 @@ public function testTypeConversionWithDirectExpression(): void
         $mongoDate = new UTCDateTime((int) $dateTime->format('Uv'));
         $stage     = $builder
             ->replaceRoot(
-                $builder->expr()
+                $builder->createAggregationExpression()
                     ->field('isToday')
                     ->eq('$createdAt', $dateTime)
             );
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Functional/QueryTest.php b/tests/Doctrine/ODM/MongoDB/Tests/Functional/QueryTest.php
index a5132850e1..c66e763cea 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Functional/QueryTest.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Functional/QueryTest.php
@@ -53,7 +53,7 @@ public function testAddElemMatch(): void
         $qb         = $this->dm->createQueryBuilder(User::class);
         $embeddedQb = $this->dm->createQueryBuilder(Phonenumber::class);
 
-        $qb->field('phonenumbers')->elemMatch($embeddedQb->expr()->field('phonenumber')->equals('6155139185'));
+        $qb->field('phonenumbers')->elemMatch($embeddedQb->createQueryExpression()->field('phonenumber')->equals('6155139185'));
         $query = $qb->getQuery();
         $user  = $query->getSingleResult();
         self::assertNotNull($user);
@@ -76,7 +76,8 @@ public function testAddElemMatchWithDeepFields(): void
         $qb         = $this->dm->createQueryBuilder(User::class);
         $embeddedQb = $this->dm->createQueryBuilder(Phonenumber::class);
 
-        $qb->field('phonenumbers')->elemMatch($embeddedQb->expr()->field('lastCalledBy.$id')->equals(new ObjectId($user1->getId())));
+        $qb->field('phonenumbers')->elemMatch($embeddedQb->createQueryExpression()->field('lastCalledBy.$id')->equals(new ObjectId
+        ($user1->getId())));
         $query = $qb->getQuery();
         $user  = $query->getSingleResult();
         self::assertNotNull($user);
@@ -91,12 +92,12 @@ public function testAddNot(): void
         $this->dm->flush();
 
         $qb = $this->dm->createQueryBuilder(User::class);
-        $qb->field('username')->not($qb->expr()->in(['boo']));
+        $qb->field('username')->not($qb->createQueryExpression()->in(['boo']));
         $query = $qb->getQuery();
         $user  = $query->getSingleResult();
         self::assertNull($user);
 
-        $qb->field('username')->not($qb->expr()->in(['1boo']));
+        $qb->field('username')->not($qb->createQueryExpression()->in(['1boo']));
         $query = $qb->getQuery();
         $user  = $query->getSingleResult();
         self::assertNotNull($user);
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1674Test.php b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1674Test.php
index 9bf8e0ab93..4c1a2f3e5b 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1674Test.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH1674Test.php
@@ -18,7 +18,7 @@ public function testElemMatchUsesCorrectMapping(): void
         $builder
             ->field('embedded')
             ->elemMatch(
-                $builder->expr()
+                $builder->createQueryExpression()
                     ->field('id')
                     ->equals(1)
             );
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH2251Test.php b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH2251Test.php
index ac2cc32d9a..eb5512888b 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH2251Test.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH2251Test.php
@@ -23,8 +23,8 @@ public function testElemMatchQuery(string $fieldName): void
             new ObjectId('5fae9a775ef4492e3c72b3f4'),
         ];
 
-        $notIn     = $builder->expr()->notIn($objectIds);
-        $elemMatch = $builder->expr()
+        $notIn     = $builder->createQueryExpression()->notIn($objectIds);
+        $elemMatch = $builder->createQueryExpression()
             ->field($fieldName)
             ->elemMatch($notIn);
 
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH596Test.php b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH596Test.php
index 5350aea919..bbf34bb157 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH596Test.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Functional/Ticket/GH596Test.php
@@ -26,8 +26,8 @@ public function testExpressionPreparationDoesNotInjectFilterCriteria(): void
 
         $repository = $this->dm->getRepository($class);
         $qb         = $repository->createQueryBuilder();
-        $qb->addOr($qb->expr()->field('name')->equals('foo'));
-        $qb->addOr($qb->expr()->field('name')->equals('bar'));
+        $qb->addOr($qb->createQueryExpression()->field('name')->equals('foo'));
+        $qb->addOr($qb->createQueryExpression()->field('name')->equals('bar'));
 
         $query = $qb->getQuery();
         $query = $query->getQuery();
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Query/BuilderTest.php b/tests/Doctrine/ODM/MongoDB/Tests/Query/BuilderTest.php
index 4e6ac2ef4b..e817229495 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Query/BuilderTest.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Query/BuilderTest.php
@@ -242,8 +242,8 @@ public function provideArrayUpdateOperatorsOnReferenceOne(): Generator
     public function testThatOrAcceptsAnotherQuery(): void
     {
         $qb = $this->getTestQueryBuilder();
-        $qb->addOr($qb->expr()->field('firstName')->equals('Kris'));
-        $qb->addOr($qb->expr()->field('firstName')->equals('Chris'));
+        $qb->addOr($qb->createQueryExpression()->field('firstName')->equals('Kris'));
+        $qb->addOr($qb->createQueryExpression()->field('firstName')->equals('Chris'));
 
         self::assertEquals([
             '$or' => [
@@ -256,8 +256,8 @@ public function testThatOrAcceptsAnotherQuery(): void
     public function testThatAndAcceptsAnotherQuery(): void
     {
         $qb = $this->getTestQueryBuilder();
-        $qb->addAnd($qb->expr()->field('hits')->gte(1));
-        $qb->addAnd($qb->expr()->field('hits')->lt(5));
+        $qb->addAnd($qb->createQueryExpression()->field('hits')->gte(1));
+        $qb->addAnd($qb->createQueryExpression()->field('hits')->lt(5));
 
         self::assertEquals([
             '$and' => [
@@ -270,8 +270,8 @@ public function testThatAndAcceptsAnotherQuery(): void
     public function testThatNorAcceptsAnotherQuery(): void
     {
         $qb = $this->getTestQueryBuilder();
-        $qb->addNor($qb->expr()->field('firstName')->equals('Kris'));
-        $qb->addNor($qb->expr()->field('firstName')->equals('Chris'));
+        $qb->addNor($qb->createQueryExpression()->field('firstName')->equals('Kris'));
+        $qb->addNor($qb->createQueryExpression()->field('firstName')->equals('Chris'));
 
         self::assertEquals([
             '$nor' => [
@@ -284,7 +284,7 @@ public function testThatNorAcceptsAnotherQuery(): void
     public function testAddElemMatch(): void
     {
         $qb = $this->getTestQueryBuilder();
-        $qb->field('phonenumbers')->elemMatch($qb->expr()->field('phonenumber')->equals('6155139185'));
+        $qb->field('phonenumbers')->elemMatch($qb->createQueryExpression()->field('phonenumber')->equals('6155139185'));
         $expected = [
             'phonenumbers' => [
                 '$elemMatch' => ['phonenumber' => '6155139185'],
@@ -296,7 +296,7 @@ public function testAddElemMatch(): void
     public function testAddNot(): void
     {
         $qb = $this->getTestQueryBuilder();
-        $qb->field('username')->not($qb->expr()->in(['boo']));
+        $qb->field('username')->not($qb->createQueryExpression()->in(['boo']));
         $expected = [
             'username' => [
                 '$not' => [
@@ -662,7 +662,7 @@ public function testSelectElemMatchWithArray(): void
     public function testSelectElemMatchWithExpr(): void
     {
         $qb = $this->getTestQueryBuilder();
-        $qb->selectElemMatch('addresses', $qb->expr()->field('state')->equals('ny'));
+        $qb->selectElemMatch('addresses', $qb->createQueryExpression()->field('state')->equals('ny'));
 
         $expected = ['addresses' => ['$elemMatch' => ['state' => 'ny']]];
 
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/Query/ExprTest.php b/tests/Doctrine/ODM/MongoDB/Tests/Query/ExprTest.php
index 661763d831..cc1da7834a 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/Query/ExprTest.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/Query/ExprTest.php
@@ -87,7 +87,7 @@ public function testAndIsPrepared(): void
 
         $qb = $this->dm->createQueryBuilder(User::class);
         $qb
-            ->addAnd($qb->expr()->field('groups.id')->in($ids))
+            ->addAnd($qb->createQueryExpression()->field('groups.id')->in($ids))
             ->select('id')->hydrate(false);
         $query = $qb->getQuery();
         $debug = $query->debug('query');
@@ -102,7 +102,7 @@ public function testOrIsPrepared(): void
 
         $qb = $this->dm->createQueryBuilder(User::class);
         $qb
-            ->addOr($qb->expr()->field('groups.id')->in($ids))
+            ->addOr($qb->createQueryExpression()->field('groups.id')->in($ids))
             ->select('id')->hydrate(false);
         $query = $qb->getQuery();
         $debug = $query->debug('query');
diff --git a/tests/Doctrine/ODM/MongoDB/Tests/QueryTest.php b/tests/Doctrine/ODM/MongoDB/Tests/QueryTest.php
index abed16a68c..e1d58dbe19 100644
--- a/tests/Doctrine/ODM/MongoDB/Tests/QueryTest.php
+++ b/tests/Doctrine/ODM/MongoDB/Tests/QueryTest.php
@@ -59,8 +59,8 @@ public function testThatOrAcceptsAnotherQuery(): void
         $expression2 = ['firstName' => 'Chris'];
 
         $qb = $this->dm->createQueryBuilder($class);
-        $qb->addOr($qb->expr()->field('firstName')->equals('Kris'));
-        $qb->addOr($qb->expr()->field('firstName')->equals('Chris'));
+        $qb->addOr($qb->createQueryExpression()->field('firstName')->equals('Kris'));
+        $qb->addOr($qb->createQueryExpression()->field('firstName')->equals('Chris'));
 
         self::assertEquals([
             '$or' => [
@@ -283,7 +283,7 @@ public function testElemMatch(): void
         $qb         = $this->dm->createQueryBuilder(User::class);
         $embeddedQb = $this->dm->createQueryBuilder(Phonenumber::class);
 
-        $qb->field('phonenumbers')->elemMatch($embeddedQb->expr()
+        $qb->field('phonenumbers')->elemMatch($embeddedQb->createQueryExpression()
             ->field('lastCalledBy.id')->equals($refId));
         $query = $qb->getQuery();
 

From b5b2a8277a6df7749177428d5294211ee2766e5c Mon Sep 17 00:00:00 2001
From: Vincent Le Henaff <v.le-henaff@outlook.com>
Date: Fri, 11 Nov 2022 03:47:24 +0100
Subject: [PATCH 31/31] + adding regexMatch to Aggretation

---
 lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
index 29e2d2fadb..7f51f12b92 100644
--- a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
+++ b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
@@ -1119,6 +1119,20 @@ public function reduce($input, $initialValue, $in): self
         return $this->operator('$reduce', ['input' => $input, 'initialValue' => $initialValue, 'in' => $in]);
     }
 
+    /**
+     * Performs a regular expression (regex) pattern matching
+     *
+     * @see https://docs.mongodb.com/manual/reference/operator/aggregation/regexMatch/
+     *
+     * @param mixed|self $input   The value to compare. (Use "$<field>" format to test your regex on a field)
+     * @param mixed|self $regex   The regular expression (regex)
+     * @param mixed|self $options A string containing regex flags options. See mongodb doc. above for details
+     */
+    public function regexMatch($input, $regex, $options): self
+    {
+        return $this->operator('$regexMatch', ['input' => $input, 'regex' => $regex, 'options' => $options]);
+    }
+
     /**
      * Accepts an array expression as an argument and returns an array with the
      * elements in reverse order.