Improve query and aggregator classes (doctrine#2702)

* Add joint iterable interface for queries and aggregations

* Update declared return types for query and aggregation builders

Author: alcaeus

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

@@ -7,19 +7,19 @@
 use Doctrine\ODM\MongoDB\DocumentManager;
 use Doctrine\ODM\MongoDB\Iterator\CachingIterator;
 use Doctrine\ODM\MongoDB\Iterator\HydratingIterator;
+use Doctrine\ODM\MongoDB\Iterator\IterableResult;
 use Doctrine\ODM\MongoDB\Iterator\Iterator;
 use Doctrine\ODM\MongoDB\Iterator\UnrewindableIterator;
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Iterator as SPLIterator;
-use IteratorAggregate;
 use MongoDB\Collection;
 use MongoDB\Driver\CursorInterface;
 
 use function array_merge;
 use function assert;
 
 /** @phpstan-import-type PipelineExpression from Builder */
-final class Aggregation implements IteratorAggregate
+final class Aggregation implements IterableResult
 {
     /**
      * @param array<string, mixed> $pipeline
@@ -30,6 +30,26 @@ public function __construct(private DocumentManager $dm, private ?ClassMetadata
     {
     }
 
+    public function execute(): Iterator
+    {
+        return $this->getIterator();
+    }
+
+    /**
+     * Execute the query and return the first result.
+     *
+     * @return array<string, mixed>|object|null
+     */
+    public function getSingleResult(): mixed
+    {
+        $clone = clone $this;
+
+        // Limit the pipeline to a single result for efficiency
+        $this->pipeline[] = ['$limit' => 1];
+
+        return $clone->getIterator()->current() ?: null;
+    }
+
     public function getIterator(): Iterator
     {
         // Force cursor to be used

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

@@ -6,6 +6,7 @@
 
 use Doctrine\ODM\MongoDB\Aggregation\Stage\Sort;
 use Doctrine\ODM\MongoDB\DocumentManager;
+use Doctrine\ODM\MongoDB\Iterator\IterableResult;
 use Doctrine\ODM\MongoDB\Iterator\Iterator;
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\Persisters\DocumentPersister;
@@ -246,8 +247,10 @@ public function geoNear($x, $y = null): Stage\GeoNear
      * Returns an aggregation object for the current pipeline
      *
      * @param array<string, mixed> $options
+     *
+     * @return Aggregation
      */
-    public function getAggregation(array $options = []): Aggregation
+    public function getAggregation(array $options = []): IterableResult
     {
         $class = $this->hydrationClass ? $this->dm->getClassMetadata($this->hydrationClass) : null;
 

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

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ODM\MongoDB\Iterator;
+
+use BadMethodCallException;
+use IteratorAggregate;
+
+interface IterableResult extends IteratorAggregate
+{
+    /**
+     * Executes the operation and returns a result if available; null otherwise
+     */
+    public function execute(): mixed;
+
+    /**
+     * Executes the operation and returns a result iterator. If the operation
+     * did not yield an iterator, this method will throw
+     *
+     * @throws BadMethodCallException if the operation did not yield an iterator.
+     */
+    public function getIterator(): Iterator;
+
+    /**
+     * Returns the first result only from the operation
+     *
+     * Note that the behaviour of fetching the first result is dependent on the
+     * implementation. A separate operation might be involved.
+     */
+    public function getSingleResult(): mixed;
+}

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

@@ -7,6 +7,7 @@
 use BadMethodCallException;
 use Doctrine\ODM\MongoDB\Aggregation\Stage\Sort;
 use Doctrine\ODM\MongoDB\DocumentManager;
+use Doctrine\ODM\MongoDB\Iterator\IterableResult;
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use GeoJson\Geometry\Geometry;
 use GeoJson\Geometry\Point;
@@ -659,8 +660,10 @@ public function getNewObj(): array
      * Gets the Query executable.
      *
      * @param array<string, mixed> $options
+     *
+     * @return Query
      */
-    public function getQuery(array $options = []): Query
+    public function getQuery(array $options = []): IterableResult
     {
         $documentPersister = $this->dm->getUnitOfWork()->getDocumentPersister($this->class->name);
 

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

@@ -9,14 +9,14 @@
 use Doctrine\ODM\MongoDB\DocumentManager;
 use Doctrine\ODM\MongoDB\Iterator\CachingIterator;
 use Doctrine\ODM\MongoDB\Iterator\HydratingIterator;
+use Doctrine\ODM\MongoDB\Iterator\IterableResult;
 use Doctrine\ODM\MongoDB\Iterator\Iterator;
 use Doctrine\ODM\MongoDB\Iterator\PrimingIterator;
 use Doctrine\ODM\MongoDB\Iterator\UnrewindableIterator;
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\MongoDBException;
 use Doctrine\ODM\MongoDB\UnitOfWork;
 use InvalidArgumentException;
-use IteratorAggregate;
 use MongoDB\Collection;
 use MongoDB\DeleteResult;
 use MongoDB\Driver\ReadPreference;
@@ -63,7 +63,7 @@
  * @phpstan-import-type Hints from UnitOfWork
  * @phpstan-import-type SortMeta from Sort
  */
-final class Query implements IteratorAggregate
+final class Query implements IterableResult
 {
     public const TYPE_FIND            = 1;
     public const TYPE_FIND_AND_UPDATE = 2;
@@ -200,7 +200,7 @@ public function debug(?string $name = null)
      *
      * @throws MongoDBException
      */
-    public function execute()
+    public function execute(): mixed
     {
         $results = $this->runQuery();
 
@@ -296,7 +296,7 @@ public function getQuery(): array
      *
      * @return array<string, mixed>|object|null
      */
-    public function getSingleResult()
+    public function getSingleResult(): mixed
     {
         $clonedQuery                 = clone $this;
         $clonedQuery->query['limit'] = 1;
@@ -353,7 +353,7 @@ public function setRewindable(bool $rewindable = true): void
     /**
      * Execute the query and return its results as an array.
      *
-     * @see IteratorAggregate::toArray()
+     * @see Iterator::toArray()
      *
      * @return mixed[]
      */