Specify iterator types in Aggregation namespace (#2433)

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

@@ -28,15 +28,19 @@ final class Aggregation implements IteratorAggregate
     /** @var Collection */
     private $collection;
 
-    /** @var array */
+    /** @var array<string, mixed> */
     private $pipeline;
 
-    /** @var array */
+    /** @var array<string, mixed> */
     private $options;
 
     /** @var bool */
     private $rewindable;
 
+    /**
+     * @param array<string, mixed> $pipeline
+     * @param array<string, mixed> $options
+     */
     public function __construct(DocumentManager $dm, ?ClassMetadata $classMetadata, Collection $collection, array $pipeline, array $options = [], bool $rewindable = true)
     {
         $this->dm            = $dm;

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

@@ -171,6 +171,8 @@ public function count(string $fieldName): Stage\Count
      * Executes the aggregation pipeline
      *
      * @deprecated This method was deprecated in doctrine/mongodb-odm 2.2. Please use getAggregation() instead.
+     *
+     * @param array<string, mixed> $options
      */
     public function execute(array $options = []): Iterator
     {
@@ -217,8 +219,8 @@ public function facet(): Stage\Facet
      *
      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/geoNear/
      *
-     * @param float|array|Point $x
-     * @param float             $y
+     * @param float|array<string, mixed>|Point $x
+     * @param float                            $y
      */
     public function geoNear($x, $y = null): Stage\GeoNear
     {
@@ -230,6 +232,8 @@ public function geoNear($x, $y = null): Stage\GeoNear
 
     /**
      * Returns an aggregation object for the current pipeline
+     *
+     * @param array<array<string, mixed>> $options
      */
     public function getAggregation(array $options = []): Aggregation
     {
@@ -253,6 +257,8 @@ public function getAggregation(array $options = []): Aggregation
      * For aggregation pipelines that will be nested (e.g. in a facet stage),
      * you should not apply filters as this may cause wrong results to be
      * given.
+     *
+     * @return array<array<string, mixed>>
      */
     // phpcs:enable Squiz.Commenting.FunctionComment.ExtraParamComment
     public function getPipeline(/* bool $applyFilters = true */): array
@@ -470,7 +476,7 @@ public function redact(): Stage\Redact
      * including the _id field. You can promote an existing embedded document to
      * the top level, or create a new document for promotion.
      *
-     * @param string|array|Expr|null $expression Optional. A replacement expression that
+     * @param string|mixed[]|Expr|null $expression Optional. A replacement expression that
      * resolves to a document.
      */
     public function replaceRoot($expression = null): Stage\ReplaceRoot
@@ -527,8 +533,8 @@ public function skip(int $skip): Stage\Skip
      *
      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/sort/
      *
-     * @param array|string $fieldName Field name or array of field/order pairs
-     * @param int|string   $order     Field order (if one field is specified)
+     * @param array<string, int|string>|string $fieldName Field name or array of field/order pairs
+     * @param int|string                       $order     Field order (if one field is specified)
      */
     public function sort($fieldName, $order = null): Stage\Sort
     {
@@ -584,6 +590,10 @@ public function addStage(Stage $stage): Stage
 
     /**
      * Applies filters and discriminator queries to the pipeline
+     *
+     * @param array<string, mixed> $query
+     *
+     * @return array<string, mixed>
      */
     private function applyFilters(array $query): array
     {

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

@@ -41,7 +41,7 @@ class Expr
      */
     private $currentField;
 
-    /** @var array|null */
+    /** @var array{case: mixed|self, then?: mixed|self}|null */
     private $switchBranch;
 
     public function __construct(DocumentManager $dm, ClassMetadataInterface $class)
@@ -90,8 +90,8 @@ public function add($expression1, $expression2, ...$expressions): self
      *
      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/and/
      *
-     * @param array|self $expression
-     * @param array|self ...$expressions
+     * @param array<string, mixed>|self $expression
+     * @param array<string, mixed>|self ...$expressions
      */
     public function addAnd($expression, ...$expressions): self
     {
@@ -109,8 +109,8 @@ public function addAnd($expression, ...$expressions): self
      *
      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/or/
      *
-     * @param array|self $expression
-     * @param array|self ...$expressions
+     * @param array<string, mixed>|self $expression
+     * @param array<string, mixed>|self ...$expressions
      */
     public function addOr($expression, ...$expressions): self
     {
@@ -162,7 +162,7 @@ public function allElementsTrue($expression): self
      *
      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/anyElementTrue/
      *
-     * @param array|self $expression
+     * @param mixed[]|self $expression
      */
     public function anyElementTrue($expression): self
     {
@@ -313,7 +313,7 @@ public function cond($if, $then, $else): self
      *
      * @param mixed|self $expression
      *
-     * @return string|array
+     * @return string|array<string, mixed>
      */
     public static function convertExpression($expression)
     {
@@ -1583,7 +1583,7 @@ private function getDocumentPersister(): DocumentPersister
      * If there is a current field, the operator will be set on it; otherwise,
      * the operator is set at the top level of the query.
      *
-     * @param array|self $expression
+     * @param mixed[]|self $expression
      */
     private function operator(string $operator, $expression): self
     {

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

@@ -35,6 +35,8 @@ abstract public function getExpression(): array;
      * Executes the aggregation pipeline
      *
      * @deprecated This method was deprecated in doctrine/mongodb-odm 2.2. Please use getAggregation() instead.
+     *
+     * @param array<string, mixed> $options
      */
     public function execute(array $options = []): Iterator
     {
@@ -51,6 +53,8 @@ public function execute(array $options = []): Iterator
 
     /**
      * Returns an aggregation object for the current pipeline
+     *
+     * @param array<string, mixed> $options
      */
     public function getAggregation(array $options = []): Aggregation
     {
@@ -150,8 +154,8 @@ public function facet(): Stage\Facet
      *
      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/geoNear/
      *
-     * @param float|array|Point $x
-     * @param float             $y
+     * @param float|array<string, mixed>|Point $x
+     * @param float                            $y
      */
     public function geoNear($x, $y = null): Stage\GeoNear
     {
@@ -160,6 +164,8 @@ public function geoNear($x, $y = null): Stage\GeoNear
 
     /**
      * Returns the assembled aggregation pipeline
+     *
+     * @return array<array<string, mixed>>
      */
     public function getPipeline(): array
     {
@@ -278,7 +284,7 @@ public function redact(): Stage\Redact
      * including the _id field. You can promote an existing embedded document to
      * the top level, or create a new document for promotion.
      *
-     * @param string|array|null $expression Optional. A replacement expression that
+     * @param string|mixed[]|null $expression Optional. A replacement expression that
      * resolves to a document.
      */
     public function replaceRoot($expression = null): Stage\ReplaceRoot
@@ -336,8 +342,8 @@ public function sortByCount(string $expression): Stage\SortByCount
      *
      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/sort/
      *
-     * @param array|string $fieldName Field name or array of field/order pairs
-     * @param int|string   $order     Field order (if one field is specified)
+     * @param array<string, int|string>|string $fieldName Field name or array of field/order pairs
+     * @param int|string                       $order     Field order (if one field is specified)
      */
     public function sort($fieldName, $order = null): Stage\Sort
     {

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

@@ -33,7 +33,7 @@ abstract class AbstractBucket extends Stage
     /** @var Bucket\AbstractOutput|null */
     protected $output;
 
-    /** @var Expr|array|string */
+    /** @var Expr|array<string, mixed>|string */
     protected $groupBy;
 
     public function __construct(Builder $builder, DocumentManager $documentManager, ClassMetadata $class)
@@ -48,7 +48,7 @@ public function __construct(Builder $builder, DocumentManager $documentManager,
      * An expression to group documents by. To specify a field path, prefix the
      * field name with a dollar sign $ and enclose it in quotes.
      *
-     * @param array|Expr|string $expression
+     * @param array<string, mixed>|Expr|string $expression
      */
     public function groupBy($expression): self
     {
@@ -72,6 +72,9 @@ public function getExpression(): array
         return $stage;
     }
 
+    /**
+     * @return mixed[]
+     */
     abstract protected function getExtraPipelineFields(): array;
 
     /**

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

@@ -11,7 +11,7 @@
  */
 class Bucket extends AbstractBucket
 {
-    /** @var array */
+    /** @var mixed[] */
     private $boundaries;
 
     /** @var mixed */
@@ -65,6 +65,9 @@ public function output(): Bucket\BucketOutput
         return $this->output;
     }
 
+    /**
+     * @return array{boundaries: mixed[], default: mixed}
+     */
     protected function getExtraPipelineFields(): array
     {
         $fields = ['boundaries' => $this->boundaries];

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Bucket/BucketAutoOutput.php

@@ -24,7 +24,7 @@ public function __construct(Builder $builder, Stage\BucketAuto $bucket)
      * An expression to group documents by. To specify a field path, prefix the
      * field name with a dollar sign $ and enclose it in quotes.
      *
-     * @param array|Expr|string $expression
+     * @param array<string, mixed>|Expr|string $expression
      */
     public function groupBy($expression): Stage\BucketAuto
     {

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Bucket/BucketOutput.php

@@ -44,7 +44,7 @@ public function groupBy($expression)
      * boundaries. The specified values must be in ascending order and all of
      * the same type. The exception is if the values are of mixed numeric types.
      *
-     * @param array ...$boundaries
+     * @param mixed ...$boundaries
      *
      * @return Stage\Bucket
      */

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

@@ -14,7 +14,7 @@ class BucketAuto extends AbstractBucket
     /** @var int */
     private $buckets;
 
-    /** @var string */
+    /** @var string|null */
     private $granularity;
 
     /**
@@ -56,6 +56,9 @@ public function output(): Bucket\BucketAutoOutput
         return $this->output;
     }
 
+    /**
+     * @return array{buckets: int, granularity?: string}
+     */
     protected function getExtraPipelineFields(): array
     {
         $fields = ['buckets' => $this->buckets];

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

@@ -29,7 +29,7 @@ class GeoNear extends MatchStage
     /** @var float */
     private $minDistance;
 
-    /** @var array */
+    /** @var array<string, mixed>|array{int|float, int|float} */
     private $near;
 
     /** @var int */
@@ -42,8 +42,8 @@ class GeoNear extends MatchStage
     private $uniqueDocs;
 
     /**
-     * @param float|array|Point $x
-     * @param float             $y
+     * @param float|array<string, mixed>|Point $x
+     * @param float                            $y
      */
     public function __construct(Builder $builder, $x, $y = null)
     {
@@ -144,8 +144,8 @@ public function minDistance(float $minDistance): self
      * an array corresponding to the point's JSON representation. If GeoJSON is
      * used, the "spherical" option will default to true.
      *
-     * @param float|array|Point $x
-     * @param float             $y
+     * @param float|array<string, mixed>|Point $x
+     * @param float                            $y
      */
     public function near($x, $y = null): self
     {

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

@@ -20,12 +20,15 @@
 use function is_string;
 use function substr;
 
+/**
+ * @psalm-import-type FieldMapping from ClassMetadata
+ */
 class GraphLookup extends Stage
 {
     /** @var string|null */
     private $from;
 
-    /** @var string|Expr|array|null */
+    /** @var string|Expr|mixed[]|null */
     private $startWith;
 
     /** @var string|null */
@@ -230,7 +233,7 @@ public function restrictSearchWithMatch(): GraphLookup\MatchStage
      * Optionally, startWith may be array of values, each of which is
      * individually followed through the traversal process.
      *
-     * @param string|array|Expr $expression
+     * @param string|mixed[]|Expr $expression
      */
     public function startWith($expression): self
     {
@@ -308,6 +311,9 @@ private function getDocumentPersister(ClassMetadata $class): DocumentPersister
         return $this->dm->getUnitOfWork()->getDocumentPersister($class->name);
     }
 
+    /**
+     * @psalm-param FieldMapping $mapping
+     */
     private function getReferencedFieldName(string $fieldName, array $mapping): string
     {
         if (! $this->targetClass) {

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

@@ -45,7 +45,7 @@ public function from(string $from): GraphLookup
      * Optionally, startWith may be array of values, each of which is
      * individually followed through the traversal process.
      *
-     * @param string|array|Expr $expression
+     * @param string|mixed[]|Expr $expression
      */
     public function startWith($expression): GraphLookup
     {