Add support for PHP 8.4 Lazy Objects with configuration flag

Author: GromNaN

.github/workflows/continuous-integration.yml

@@ -77,6 +77,13 @@ jobs:
             dependencies: "highest"
             symfony-version: "stable"
             proxy: "proxy-manager"
+          # Test with Native Lazy Objects
+          - php-version: "8.4"
+            mongodb-version: "8.0"
+            driver-version: "stable"
+            dependencies: "highest"
+            symfony-version: "stable"
+            proxy: "native"
           # Test with extension 1.21
           - topology: "server"
             php-version: "8.2"
@@ -163,4 +170,5 @@ jobs:
         env:
           DOCTRINE_MONGODB_SERVER: ${{ steps.setup-mongodb.outputs.cluster-uri }}
           USE_LAZY_GHOST_OBJECTS: ${{ matrix.proxy == 'lazy-ghost' && '1' || '0' }}"
+          USE_NATIVE_LAZY_OBJECTS: ${{ matrix.proxy == 'native' && '1' || '0' }}"
           CRYPT_SHARED_LIB_PATH: ${{ steps.setup-mongodb.outputs.crypt-shared-lib-path }}

lib/Doctrine/ODM/MongoDB/Configuration.php

@@ -47,6 +47,8 @@
 use function trigger_deprecation;
 use function trim;
 
+use const PHP_VERSION_ID;
+
 /**
  * Configuration class for the DocumentManager. When setting up your DocumentManager
  * you can optionally specify an instance of this class as the second argument.
@@ -145,7 +147,8 @@ class Configuration
 
     private bool $useTransactionalFlush = false;
 
-    private bool $useLazyGhostObject = false;
+    private bool $lazyGhostObject   = false;
+    private bool $nativeLazyObjects = false;
 
     private static string $version;
 
@@ -686,26 +689,49 @@ public function isTransactionalFlushEnabled(): bool
      * Generate proxy classes using Symfony VarExporter's LazyGhostTrait if true.
      * Otherwise, use ProxyManager's LazyLoadingGhostFactory (deprecated)
      */
-    public function setUseLazyGhostObject(bool $flag): void
+    public function setLazyGhostObject(bool $flag): void
     {
-        if ($flag === false) {
+        if ($this->nativeLazyObjects) {
+            throw new LogicException('Cannot enable or disable LazyGhostObject when native lazy objects are enabled.');
+        }
+
+        if ($flag) {
             if (! class_exists(ProxyManagerConfiguration::class)) {
                 throw new LogicException('Package "friendsofphp/proxy-manager-lts" is required to disable LazyGhostObject.');
             }
 
-            trigger_deprecation(
-                'doctrine/mongodb-odm',
-                '2.10',
-                'Using "friendsofphp/proxy-manager-lts" is deprecated. Use "symfony/var-exporter" LazyGhostObjects instead.',
-            );
+            trigger_deprecation('doctrine/mongodb-odm', '2.10', 'Using "friendsofphp/proxy-manager-lts" is deprecated. Use "symfony/var-exporter" LazyGhostObjects instead.');
         }
 
-        $this->useLazyGhostObject = $flag;
+        if ($flag === true && PHP_VERSION_ID >= 80400) {
+            trigger_deprecation('doctrine/mongodb-odm', '2.13', 'Using "symfony/var-exporter" lazy ghost objects is deprecated and will be impossible in Doctrine MongoDB ODM 3.0.');
+        }
+
+        $this->lazyGhostObject = $flag;
     }
 
     public function isLazyGhostObjectEnabled(): bool
     {
-        return $this->useLazyGhostObject;
+        return $this->lazyGhostObject;
+    }
+
+    public function enableNativeLazyObjects(bool $nativeLazyObjects): void
+    {
+        if (PHP_VERSION_ID >= 80400 && ! $nativeLazyObjects) {
+            trigger_deprecation('doctrine/mongodb-odm', '2.13', 'Disabling native lazy objects is deprecated and will be impossible in Doctrine MongoDB ODM 3.0.');
+        }
+
+        if (PHP_VERSION_ID < 80400 && $nativeLazyObjects) {
+            throw new LogicException('Lazy loading proxies require PHP 8.4 or higher.');
+        }
+
+        $this->nativeLazyObjects = $nativeLazyObjects;
+        $this->lazyGhostObject   = ! $nativeLazyObjects || $this->lazyGhostObject;
+    }
+
+    public function isNativeLazyObjectsEnabled(): bool
+    {
+        return $this->nativeLazyObjects;
     }
 
     /**

lib/Doctrine/ODM/MongoDB/DocumentManager.php

@@ -10,6 +10,7 @@
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadataFactoryInterface;
 use Doctrine\ODM\MongoDB\Mapping\MappingException;
 use Doctrine\ODM\MongoDB\Proxy\Factory\LazyGhostProxyFactory;
+use Doctrine\ODM\MongoDB\Proxy\Factory\NativeLazyObjectFactory;
 use Doctrine\ODM\MongoDB\Proxy\Factory\ProxyFactory;
 use Doctrine\ODM\MongoDB\Proxy\Factory\StaticProxyFactory;
 use Doctrine\ODM\MongoDB\Proxy\Resolver\CachingClassNameResolver;
@@ -31,7 +32,6 @@
 use MongoDB\Driver\ClientEncryption;
 use MongoDB\Driver\ReadPreference;
 use MongoDB\GridFS\Bucket;
-use ProxyManager\Proxy\GhostObjectInterface;
 use RuntimeException;
 use Throwable;
 
@@ -179,11 +179,13 @@ protected function __construct(?Client $client = null, ?Configuration $config =
             $this->config->getAutoGenerateHydratorClasses(),
         );
 
-        $this->unitOfWork        = new UnitOfWork($this, $this->eventManager, $this->hydratorFactory);
-        $this->schemaManager     = new SchemaManager($this, $this->metadataFactory);
-        $this->proxyFactory      = $this->config->isLazyGhostObjectEnabled()
-            ? new LazyGhostProxyFactory($this, $this->config->getProxyDir(), $this->config->getProxyNamespace(), $this->config->getAutoGenerateProxyClasses())
-            : new StaticProxyFactory($this);
+        $this->unitOfWork    = new UnitOfWork($this, $this->eventManager, $this->hydratorFactory);
+        $this->schemaManager = new SchemaManager($this, $this->metadataFactory);
+        $this->proxyFactory  = match (true) {
+            $this->config->isNativeLazyObjectsEnabled() => new NativeLazyObjectFactory($this->unitOfWork),
+            $this->config->isLazyGhostObjectEnabled() => new LazyGhostProxyFactory($this, $this->config->getProxyDir(), $this->config->getProxyNamespace(), $this->config->getAutoGenerateProxyClasses()),
+            default => new StaticProxyFactory($this),
+        };
         $this->repositoryFactory = $this->config->getRepositoryFactory();
     }
 
@@ -607,7 +609,7 @@ public function flush(array $options = []): void
      * @param mixed           $identifier
      * @param class-string<T> $documentName
      *
-     * @return T|(T&GhostObjectInterface<T>)
+     * @return T
      *
      * @template T of object
      */
@@ -624,7 +626,7 @@ public function getReference(string $documentName, $identifier): object
             return $document;
         }
 
-        /** @var T&GhostObjectInterface<T> $document */
+        /** @var T $document */
         $document = $this->proxyFactory->getProxy($class, $identifier);
         $this->unitOfWork->registerManaged($document, $identifier, []);
 

lib/Doctrine/ODM/MongoDB/Mapping/PropertyAccessors/RawValuePropertyAccessor.php

@@ -6,6 +6,7 @@
 
 use Doctrine\ODM\MongoDB\Proxy\InternalProxy;
 use LogicException;
+use ProxyManager\Proxy\GhostObjectInterface;
 use ReflectionProperty;
 
 use function ltrim;
@@ -38,7 +39,10 @@ private function __construct(private ReflectionProperty $reflectionProperty, pri
 
     public function setValue(object $object, mixed $value): void
     {
-        if (! ($object instanceof InternalProxy && ! $object->__isInitialized())) {
+        if (
+            ! ($object instanceof InternalProxy && ! $object->__isInitialized()) &&
+            ! ($object instanceof GhostObjectInterface && ! $object->isProxyInitialized())
+        ) {
             $this->reflectionProperty->setRawValueWithoutLazyInitialization($object, $value);
 
             return;

lib/Doctrine/ODM/MongoDB/Proxy/Factory/NativeLazyObjectFactory.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ODM\MongoDB\Proxy\Factory;
+
+use Doctrine\ODM\MongoDB\DocumentNotFoundException;
+use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
+use Doctrine\ODM\MongoDB\UnitOfWork;
+use LogicException;
+use ReflectionClass;
+
+use function count;
+
+use const PHP_VERSION_ID;
+
+class NativeLazyObjectFactory implements ProxyFactory
+{
+    public function __construct(
+        private readonly UnitOfWork $unitOfWork,
+    ) {
+        if (PHP_VERSION_ID < 80400) {
+            throw new LogicException('Native lazy objects require PHP 8.4 or higher.');
+        }
+    }
+
+    public function generateProxyClasses(array $classes): int
+    {
+        // Nothing to generate, that's the point of native lazy objects
+
+        return count($classes);
+    }
+
+    public function getProxy(ClassMetadata $metadata, $identifier): object
+    {
+        $documentPersister = $this->unitOfWork->getDocumentPersister($metadata->name);
+
+        $proxy = $metadata->reflClass->newLazyGhost(static function (object $object) use (
+            $identifier,
+            $documentPersister,
+            $metadata,
+        ): void {
+            $original = $documentPersister->load([$metadata->identifier => $identifier], $object);
+            if ($original === null) {
+                throw DocumentNotFoundException::documentNotFound($metadata->name, $identifier);
+            }
+        }, ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE);
+
+        $metadata->propertyAccessors[$metadata->identifier]->setValue($proxy, $identifier);
+
+        return $proxy;
+    }
+}

lib/Doctrine/ODM/MongoDB/UnitOfWork.php

@@ -2783,12 +2783,14 @@ public function getOrCreateDocument(string $className, array $data, array &$hint
             $document = $this->identityMap[$class->name][$serializedId];
             $oid      = spl_object_id($document);
             if ($this->isUninitializedObject($document)) {
-                if ($document instanceof InternalProxy) {
+                if ($this->dm->getConfiguration()->isNativeLazyObjectsEnabled()) {
+                    $class->reflClass->markLazyObjectAsInitialized($document);
+                } elseif ($document instanceof InternalProxy) {
                     $document->__setInitialized(true);
                 } elseif ($document instanceof GhostObjectInterface) {
                     $document->setProxyInitializer(null);
                 } else {
-                    throw new \RuntimeException(sprintf('Expected uninitialized proxy or ghost object from class "%s"', $document::name));
+                    throw new \RuntimeException(sprintf('Expected uninitialized proxy or ghost object from class "%s"', $document::class));
                 }
 
                 $overrideLocalValues = true;
@@ -3090,6 +3092,7 @@ public function isUninitializedObject(object $obj): bool
             $obj instanceof InternalProxy => $obj->__isInitialized() === false,
             $obj instanceof GhostObjectInterface => $obj->isProxyInitialized() === false,
             $obj instanceof PersistentCollectionInterface => $obj->isInitialized() === false,
+            $this->dm->getConfiguration()->isNativeLazyObjectsEnabled() => $this->dm->getClassMetadata($obj::class)->reflClass->isUninitializedLazyObject($obj),
             default => false
         };
     }

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

@@ -104,7 +104,8 @@ protected static function getConfiguration(): Configuration
         $config->setPersistentCollectionNamespace('PersistentCollections');
         $config->setDefaultDB(DOCTRINE_MONGODB_DATABASE);
         $config->setMetadataDriverImpl(static::createMetadataDriverImpl());
-        $config->setUseLazyGhostObject((bool) $_ENV['USE_LAZY_GHOST_OBJECTS']);
+        $config->setLazyGhostObject((bool) $_ENV['USE_LAZY_GHOST_OBJECTS']);
+        $config->enableNativeLazyObjects((bool) $_ENV['USE_NATIVE_LAZY_OBJECTS']);
 
         $config->addFilter('testFilter', Filter::class);
         $config->addFilter('testFilter2', Filter::class);
@@ -134,6 +135,10 @@ public static function assertArraySubset(array $subset, array $array, bool $chec
 
     public static function isLazyObject(object $document): bool
     {
+        if (PHP_VERSION_ID >= 80400 && (new \ReflectionClass($document))->getLazyInitializer($document)) {
+            return true;
+        }
+
         return $document instanceof InternalProxy || $document instanceof LazyLoadingInterface;
     }
 

tests/Doctrine/ODM/MongoDB/Tests/Functional/PropertyHooksTest.php

@@ -1,8 +1,103 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Doctrine\ODM\MongoDB\Tests\Functional;
 
-class PropertyHooksTest
+use Doctrine\ODM\MongoDB\Mapping\MappingException;
+use Doctrine\ODM\MongoDB\Tests\BaseTestCase;
+use Documents\PropertyHooks\MappingVirtualProperty;
+use Documents\PropertyHooks\User;
+use PHPUnit\Framework\Attributes\RequiresPhp;
+
+#[RequiresPhp('>= 8.4.0')]
+class PropertyHooksTest extends BaseTestCase
 {
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        if ($this->dm->getConfiguration()->isNativeLazyObjectsEnabled()) {
+            return;
+        }
+
+        $this->markTestSkipped('Property hooks require native lazy objects to be enabled.');
+    }
+
+    public function testMapPropertyHooks(): void
+    {
+        $user           = new User();
+        $user->fullName = 'John Doe';
+        $user->language = 'EN';
+
+        $this->dm->persist($user);
+        $this->dm->flush();
+        $this->dm->clear();
+
+        $user = $this->dm->find(User::class, $user->id);
+
+        self::assertSame('John', $user->first);
+        self::assertSame('Doe', $user->last);
+        self::assertSame('John Doe', $user->fullName);
+        self::assertSame('EN', $user->language, 'The property hook uppercases the language.');
+
+        $document = $this->dm->createQueryBuilder()
+            ->find(User::class)
+            ->field('id')->equals($user->id)
+            ->select('language')
+            ->hydrate(false)
+            ->getQuery()
+            ->getSingleResult();
+
+        self::assertSame('en', $document['language'], 'Selecting a field without hydration does not go through the property hook, accessing raw data.');
+
+        $this->dm->clear();
+
+        $user = $this->dm->getRepository(User::class)->findOneBy(['language' => 'EN']);
+
+        self::assertNull($user);
+
+        $user = $this->dm->getRepository(User::class)->findOneBy(['language' => 'en']);
+
+        self::assertNotNull($user);
+    }
+
+    public function testTriggerLazyLoadingWhenAccessingPropertyHooks(): void
+    {
+        $user           = new User();
+        $user->fullName = 'Ludwig von Beethoven';
+        $user->language = 'DE';
+
+        $this->dm->persist($user);
+        $this->dm->flush();
+        $this->dm->clear();
+
+        $user = $this->dm->getReference(User::class, $user->id);
+
+        $this->assertTrue($this->dm->getUnitOfWork()->isUninitializedObject($user));
+
+        self::assertSame('Ludwig', $user->first);
+        self::assertSame('von Beethoven', $user->last);
+        self::assertSame('Ludwig von Beethoven', $user->fullName);
+        self::assertSame('DE', $user->language, 'The property hook uppercases the language.');
+
+        $this->assertFalse($this->dm->getUnitOfWork()->isUninitializedObject($user));
+
+        $this->dm->clear();
+
+        $user = $this->dm->getReference(User::class, $user->id);
+
+        self::assertSame('Ludwig von Beethoven', $user->fullName);
+    }
+
+    public function testMappingVirtualPropertyIsNotSupported(): void
+    {
+        // @todo remove if not relevant
+        self::markTestSkipped('Imported from ORM, but there is no virtual property support in MongoDB ODM.');
+
+        $this->expectException(MappingException::class);
+        $this->expectExceptionMessage('Mapping virtual property "fullName" on entity "Documents\PropertyHooks\MappingVirtualProperty" is not allowed.');
 
-}
+        $this->dm->getClassMetadata(MappingVirtualProperty::class);
+    }
+}

tests/Doctrine/ODM/MongoDB/Tests/Functional/ReferencePrimerTest.php

@@ -94,7 +94,6 @@ public function testPrimeReferencesWithDBRefObjects(): void
             ->field('groups')->prime(true);
 
         foreach ($qb->getQuery() as $user) {
-            self::assertTrue(self::isLazyObject($user->getAccount()));
             self::assertFalse($this->uow->isUninitializedObject($user->getAccount()));
 
             self::assertCount(2, $user->getGroups());