Merge branch '2.10.x' into proxy-var-exporter-2

composer.json

@@ -27,7 +27,7 @@
         "doctrine/collections": "^1.5 || ^2.0",
         "doctrine/event-manager": "^1.0 || ^2.0",
         "doctrine/instantiator": "^1.1 || ^2",
-        "doctrine/persistence": "^3.2",
+        "doctrine/persistence": "^3.2 || ^4",
         "jean85/pretty-package-versions": "^1.3.0 || ^2.0.1",
         "mongodb/mongodb": "^1.17.0",
         "psr/cache": "^1.0 || ^2.0 || ^3.0",

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/DocumentManager.php

@@ -23,6 +23,7 @@
 use Doctrine\ODM\MongoDB\Repository\ViewRepository;
 use Doctrine\Persistence\Mapping\ProxyClassNameResolver;
 use Doctrine\Persistence\ObjectManager;
+use Doctrine\Persistence\ObjectRepository;
 use InvalidArgumentException;
 use Jean85\PrettyVersions;
 use MongoDB\Client;
@@ -224,12 +225,8 @@ public function getClient(): Client
         return $this->client;
     }
 
-    /**
-     * Gets the metadata factory used to gather the metadata of classes.
-     *
-     * @return ClassMetadataFactoryInterface
-     */
-    public function getMetadataFactory()
+    /** Gets the metadata factory used to gather the metadata of classes. */
+    public function getMetadataFactory(): ClassmetadataFactoryInterface
     {
         return $this->metadataFactory;
     }
@@ -241,16 +238,20 @@ public function getMetadataFactory()
      *
      * @param object $obj
      */
-    public function initializeObject($obj)
+    public function initializeObject($obj): void
     {
         $this->unitOfWork->initializeObject($obj);
     }
 
     /**
      * Helper method to check whether a lazy loading proxy or persistent collection has been initialized.
      */
-    public function isUninitializedObject(object $obj): bool
+    public function isUninitializedObject(mixed $obj): bool
     {
+        if (! is_object($obj)) {
+            return false;
+        }
+
         return $this->unitOfWork->isUninitializedObject($obj);
     }
 
@@ -443,7 +444,7 @@ public function createAggregationBuilder(string $documentName): Aggregation\Buil
      *
      * @throws InvalidArgumentException When the given $object param is not an object.
      */
-    public function persist($object)
+    public function persist($object): void
     {
         if (! is_object($object)) {
             throw new InvalidArgumentException(gettype($object));
@@ -463,7 +464,7 @@ public function persist($object)
      *
      * @throws InvalidArgumentException When the $object param is not an object.
      */
-    public function remove($object)
+    public function remove($object): void
     {
         if (! is_object($object)) {
             throw new InvalidArgumentException(gettype($object));
@@ -481,7 +482,7 @@ public function remove($object)
      *
      * @throws InvalidArgumentException When the given $object param is not an object.
      */
-    public function refresh($object)
+    public function refresh($object): void
     {
         if (! is_object($object)) {
             throw new InvalidArgumentException(gettype($object));
@@ -502,7 +503,7 @@ public function refresh($object)
      *
      * @throws InvalidArgumentException When the $object param is not an object.
      */
-    public function detach($object)
+    public function detach($object): void
     {
         if (! is_object($object)) {
             throw new InvalidArgumentException(gettype($object));
@@ -562,7 +563,7 @@ public function unlock(object $document): void
      *
      * @template T of object
      */
-    public function getRepository($className)
+    public function getRepository($className): ObjectRepository
     {
         return $this->repositoryFactory->getRepository($this, $className);
     }
@@ -578,7 +579,7 @@ public function getRepository($className)
      * @throws MongoDBException
      * @throws Throwable From event listeners.
      */
-    public function flush(array $options = [])
+    public function flush(array $options = []): void
     {
         $this->errorIfClosed();
         $this->unitOfWork->commit($options);
@@ -686,7 +687,7 @@ public function find($className, $id, $lockMode = LockMode::NONE, $lockVersion =
      *
      * @param string|null $objectName if given, only documents of this type will get detached
      */
-    public function clear($objectName = null)
+    public function clear($objectName = null): void
     {
         if ($objectName !== null) {
             trigger_deprecation(
@@ -722,7 +723,7 @@ public function close()
      *
      * @throws InvalidArgumentException When the $object param is not an object.
      */
-    public function contains($object)
+    public function contains($object): bool
     {
         if (! is_object($object)) {
             throw new InvalidArgumentException(gettype($object));

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/Mapping/ClassMetadata.php

@@ -2246,7 +2246,7 @@ public function isAssociationInverseSide($assocName): bool
     }
 
     /** @param string $assocName */
-    public function getAssociationMappedByTargetField($assocName)
+    public function getAssociationMappedByTargetField($assocName): string
     {
         throw new BadMethodCallException(__METHOD__ . '() is not implemented yet.');
     }

lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadataFactory.php

@@ -40,9 +40,6 @@
  */
 final class ClassMetadataFactory extends AbstractClassMetadataFactory implements ClassMetadataFactoryInterface
 {
-    /** @var string */
-    protected $cacheSalt = '$MONGODBODMCLASSMETADATA';
-
     /** @var DocumentManager The DocumentManager instance */
     private DocumentManager $dm;
 
@@ -55,6 +52,11 @@ final class ClassMetadataFactory extends AbstractClassMetadataFactory implements
     /** @var EventManager The event manager instance */
     private EventManager $evm;
 
+    public function __construct()
+    {
+        $this->cacheSalt = '$MONGODBODMCLASSMETADATA';
+    }
+
     public function setDocumentManager(DocumentManager $dm): void
     {
         $this->dm = $dm;
@@ -82,7 +84,7 @@ protected function initialize(): void
     }
 
     /** @param string $className */
-    protected function onNotFoundMetadata($className)
+    protected function onNotFoundMetadata($className): ?ClassMetadata
     {
         if (! $this->evm->hasListeners(Events::onClassMetadataNotFound)) {
             return null;

lib/Doctrine/ODM/MongoDB/Mapping/Driver/AttributeDriver.php

@@ -62,7 +62,7 @@ public function __construct($paths = null, ?Reader $reader = null)
         $this->addPaths((array) $paths);
     }
 
-    public function isTransient($className)
+    public function isTransient($className): bool
     {
         $classAttributes = $this->getClassAttributes(new ReflectionClass($className));
 

lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php

@@ -81,7 +81,7 @@ public function __construct($locator, $fileExtension = self::DEFAULT_FILE_EXTENS
     }
 
     // phpcs:disable SlevomatCodingStandard.ControlStructures.EarlyExit.EarlyExitNotUsed
-    public function loadMetadataForClass($className, \Doctrine\Persistence\Mapping\ClassMetadata $metadata)
+    public function loadMetadataForClass($className, \Doctrine\Persistence\Mapping\ClassMetadata $metadata): void
     {
         assert($metadata instanceof ClassMetadata);
         $xmlRoot = $this->getElement($className);

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[]
      */

lib/Doctrine/ODM/MongoDB/UnitOfWork.php

@@ -2980,7 +2980,7 @@ public function clearDocumentChangeSet(string $oid): void
      * @param mixed  $oldValue     The old value of the property.
      * @param mixed  $newValue     The new value of the property.
      */
-    public function propertyChanged($sender, $propertyName, $oldValue, $newValue)
+    public function propertyChanged($sender, $propertyName, $oldValue, $newValue): void
     {
         $oid   = spl_object_hash($sender);
         $class = $this->dm->getClassMetadata($sender::class);

tests/Doctrine/ODM/MongoDB/Tests/UnitOfWorkTest.php

@@ -652,7 +652,7 @@ public function setTransient($value): void
         $this->transient = $value;
     }
 
-    public function addPropertyChangedListener(PropertyChangedListener $listener)
+    public function addPropertyChangedListener(PropertyChangedListener $listener): void
     {
         $this->_listeners[] = $listener;
     }