Add support for PHP 8.4 Lazy Objects RFC with configuration flag (#11853)

* Introduce PHP 8.4 lazy proxy/ghost API.

* Call setRawValueWithoutLazyInitialization for support with lazy proxy.

* Refactorings

* Revert test change partially and skip with lazy objects.

* Houskeeping: phpcs

* Run with ENABLE_LAZY_PROXY=1 in php 8.4 matrix.

* Fix ci

* Transient properties are not skipping lazy initialization anymore, to expensive and could lead to errors. Adjust lifecycle test that uses transient properittes for assertions.

* Restore behavior preventing property hook use in 8.4 in unsupported coditions

* Add \ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE

Co-authored-by: Nicolas Grekas <[email protected]>

* Rename isNativeLazyObjectsEnabled/enableNativeLazyObjects.

* Housekeeping: phpcs

* Update advanced-configuration docs and make proxy config variables not required anymore with native lazy objects.

* Move code around

* Apply suggestions from code review

Co-authored-by: Grégoire Paris <[email protected]>

* Pick suggestions

---------

Co-authored-by: Nicolas Grekas <[email protected]>
Co-authored-by: Grégoire Paris <[email protected]>

Author: 3 people

.github/workflows/continuous-integration.yml

@@ -43,17 +43,27 @@ jobs:
           - "pdo_sqlite"
         deps:
           - "highest"
+        lazy_proxy:
+          - "0"
         include:
           - php-version: "8.2"
             dbal-version: "4@dev"
             extension: "pdo_sqlite"
+            lazy_proxy: "0"
           - php-version: "8.2"
             dbal-version: "4@dev"
             extension: "sqlite3"
+            lazy_proxy: "0"
           - php-version: "8.1"
             dbal-version: "default"
             deps: "lowest"
             extension: "pdo_sqlite"
+            lazy_proxy: "0"
+          - php-version: "8.4"
+            dbal-version: "default"
+            deps: "highest"
+            extension: "pdo_sqlite"
+            lazy_proxy: "1"
 
     steps:
       - name: "Checkout"
@@ -83,16 +93,18 @@ jobs:
         run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage-no-cache.xml"
         env:
             ENABLE_SECOND_LEVEL_CACHE: 0
+            ENABLE_LAZY_PROXY: ${{ matrix.lazy_proxy }}
 
       - name: "Run PHPUnit with Second Level Cache"
         run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --exclude-group performance,non-cacheable,locking_functional --coverage-clover=coverage-cache.xml"
         env:
             ENABLE_SECOND_LEVEL_CACHE: 1
+            ENABLE_LAZY_PROXY: ${{ matrix.lazy_proxy }}
 
       - name: "Upload coverage file"
         uses: "actions/upload-artifact@v4"
         with:
-          name: "phpunit-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-${{ matrix.deps }}-coverage"
+          name: "phpunit-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-${{ matrix.deps }}-${{ matrix.lazy_proxy }}-coverage"
           path: "coverage*.xml"
 
 

docs/en/reference/advanced-configuration.rst

@@ -19,7 +19,7 @@ steps of configuration.
 
     // ...
 
-    if ($applicationMode == "development") {
+    if ($applicationMode === "development") {
         $queryCache = new ArrayAdapter();
         $metadataCache = new ArrayAdapter();
     } else {
@@ -32,13 +32,18 @@ steps of configuration.
     $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
     $config->setMetadataDriverImpl($driverImpl);
     $config->setQueryCache($queryCache);
-    $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
-    $config->setProxyNamespace('MyProject\Proxies');
 
-    if ($applicationMode == "development") {
-        $config->setAutoGenerateProxyClasses(true);
+    if (PHP_VERSION_ID > 80400) {
+        $config->enableNativeLazyObjects(true);
     } else {
-        $config->setAutoGenerateProxyClasses(false);
+        $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
+        $config->setProxyNamespace('MyProject\Proxies');
+
+        if ($applicationMode === "development") {
+            $config->setAutoGenerateProxyClasses(true);
+        } else {
+            $config->setAutoGenerateProxyClasses(false);
+        }
     }
 
     $connection = DriverManager::getConnection([
@@ -71,8 +76,25 @@ Configuration Options
 The following sections describe all the configuration options
 available on a ``Doctrine\ORM\Configuration`` instance.
 
-Proxy Directory (**REQUIRED**)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Native Lazy Objects (**OPTIONAL**)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With PHP 8.4 we recommend that you use native lazy objects instead of
+the code generation approach using the ``symfony/var-exporter`` Ghost trait.
+
+With Doctrine 4, the minimal requirement will become PHP 8.4 and native lazy objects
+will become the only approach to lazy loading.
+
+.. code-block:: php
+
+    <?php
+    $config->enableNativeLazyObjects(true);
+
+Proxy Directory
+~~~~~~~~~~~~~~~
+
+Required except if you use native lazy objects with PHP 8.4.
+This setting will be removed in the future.
 
 .. code-block:: php
 
@@ -85,8 +107,11 @@ classes. For a detailed explanation on proxy classes and how they
 are used in Doctrine, refer to the "Proxy Objects" section further
 down.
 
-Proxy Namespace (**REQUIRED**)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Proxy Namespace
+~~~~~~~~~~~~~~~
+
+Required except if you use native lazy objects with PHP 8.4.
+This setting will be removed in the future.
 
 .. code-block:: php
 
@@ -200,6 +225,9 @@ deprecated ``Doctrine\DBAL\Logging\SQLLogger`` interface.
 Auto-generating Proxy Classes (**OPTIONAL**)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+This setting is not required if you use native lazy objects with PHP 8.4
+and will be removed in the future.
+
 Proxy classes can either be generated manually through the Doctrine
 Console or automatically at runtime by Doctrine. The configuration
 option that controls this behavior is:

phpstan-baseline.neon

@@ -583,7 +583,7 @@ parameters:
 			path: src/EntityManager.php
 
 		-
-			message: '#^Method Doctrine\\ORM\\EntityManager\:\:getReference\(\) should return \(T of object\)\|null but returns Doctrine\\ORM\\Proxy\\InternalProxy\.$#'
+			message: '#^Method Doctrine\\ORM\\EntityManager\:\:getReference\(\) should return \(T of object\)\|null but returns object\.$#'
 			identifier: return.type
 			count: 1
 			path: src/EntityManager.php
@@ -2322,12 +2322,6 @@ parameters:
 			count: 1
 			path: src/Proxy/ProxyFactory.php
 
-		-
-			message: '#^Method Doctrine\\ORM\\Proxy\\ProxyFactory\:\:getProxy\(\) return type with generic interface Doctrine\\ORM\\Proxy\\InternalProxy does not specify its types\: T$#'
-			identifier: missingType.generics
-			count: 1
-			path: src/Proxy/ProxyFactory.php
-
 		-
 			message: '#^Method Doctrine\\ORM\\Proxy\\ProxyFactory\:\:loadProxyClass\(\) has parameter \$class with generic interface Doctrine\\Persistence\\Mapping\\ClassMetadata but does not specify its types\: T$#'
 			identifier: missingType.generics

src/Configuration.php

@@ -30,6 +30,8 @@
 use function is_a;
 use function strtolower;
 
+use const PHP_VERSION_ID;
+
 /**
  * Configuration container for all configuration options of Doctrine.
  * It combines all configuration options from DBAL & ORM.
@@ -593,6 +595,20 @@ public function setSchemaIgnoreClasses(array $schemaIgnoreClasses): void
         $this->attributes['schemaIgnoreClasses'] = $schemaIgnoreClasses;
     }
 
+    public function isNativeLazyObjectsEnabled(): bool
+    {
+        return $this->attributes['nativeLazyObjects'] ?? false;
+    }
+
+    public function enableNativeLazyObjects(bool $nativeLazyObjects): void
+    {
+        if (PHP_VERSION_ID < 80400) {
+            throw new LogicException('Lazy loading proxies require PHP 8.4 or higher.');
+        }
+
+        $this->attributes['nativeLazyObjects'] = $nativeLazyObjects;
+    }
+
     /**
      * To be deprecated in 3.1.0
      *

src/Mapping/ClassMetadataFactory.php

@@ -24,6 +24,7 @@
 use Doctrine\Persistence\Mapping\ClassMetadata as ClassMetadataInterface;
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
 use Doctrine\Persistence\Mapping\ReflectionService;
+use LogicException;
 use ReflectionClass;
 use ReflectionException;
 
@@ -41,6 +42,8 @@
 use function strtolower;
 use function substr;
 
+use const PHP_VERSION_ID;
+
 /**
  * The ClassMetadataFactory is used to create ClassMetadata objects that contain all the
  * metadata mapping information of a class which describes how a class should be mapped
@@ -296,6 +299,14 @@ protected function validateRuntimeMetadata(ClassMetadata $class, ClassMetadataIn
             // second condition is necessary for mapped superclasses in the middle of an inheritance hierarchy
             throw MappingException::noInheritanceOnMappedSuperClass($class->name);
         }
+
+        foreach ($class->propertyAccessors as $propertyAccessor) {
+            $property = $propertyAccessor->getUnderlyingReflector();
+
+            if (PHP_VERSION_ID >= 80400 && count($property->getHooks()) > 0) {
+                throw new LogicException('Doctrine ORM does not support property hooks without also enabling Configuration::enableNativeLazyObjects(true). Check https://github.com/doctrine/orm/issues/11624 for details of versions that support property hooks.');
+            }
+        }
     }
 
     protected function newClassMetadataInstance(string $className): ClassMetadata

src/Mapping/PropertyAccessors/RawValuePropertyAccessor.php

@@ -5,10 +5,13 @@
 namespace Doctrine\ORM\Mapping\PropertyAccessors;
 
 use Doctrine\ORM\Proxy\InternalProxy;
+use LogicException;
 use ReflectionProperty;
 
 use function ltrim;
 
+use const PHP_VERSION_ID;
+
 /**
  * This is a PHP 8.4 and up only class and replaces ObjectCastPropertyAccessor.
  *
@@ -28,12 +31,15 @@ public static function fromReflectionProperty(ReflectionProperty $reflectionProp
 
     private function __construct(private ReflectionProperty $reflectionProperty, private string $key)
     {
+        if (PHP_VERSION_ID < 80400) {
+            throw new LogicException('This class requires PHP 8.4 or higher.');
+        }
     }
 
     public function setValue(object $object, mixed $value): void
     {
         if (! ($object instanceof InternalProxy && ! $object->__isInitialized())) {
-            $this->reflectionProperty->setRawValue($object, $value);
+            $this->reflectionProperty->setRawValueWithoutLazyInitialization($object, $value);
 
             return;
         }

src/Proxy/ProxyFactory.php

@@ -13,6 +13,7 @@
 use Doctrine\ORM\Utility\IdentifierFlattener;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\Proxy;
+use ReflectionClass;
 use ReflectionProperty;
 use Symfony\Component\VarExporter\ProxyHelper;
 
@@ -142,11 +143,11 @@ public function __construct(
         private readonly string $proxyNs,
         bool|int $autoGenerate = self::AUTOGENERATE_NEVER,
     ) {
-        if (! $proxyDir) {
+        if (! $proxyDir && ! $em->getConfiguration()->isNativeLazyObjectsEnabled()) {
             throw ORMInvalidArgumentException::proxyDirectoryRequired();
         }
 
-        if (! $proxyNs) {
+        if (! $proxyNs && ! $em->getConfiguration()->isNativeLazyObjectsEnabled()) {
             throw ORMInvalidArgumentException::proxyNamespaceRequired();
         }
 
@@ -163,8 +164,23 @@ public function __construct(
      * @param class-string $className
      * @param array<mixed> $identifier
      */
-    public function getProxy(string $className, array $identifier): InternalProxy
+    public function getProxy(string $className, array $identifier): object
     {
+        if ($this->em->getConfiguration()->isNativeLazyObjectsEnabled()) {
+            $classMetadata   = $this->em->getClassMetadata($className);
+            $entityPersister = $this->uow->getEntityPersister($className);
+
+            $proxy = $classMetadata->reflClass->newLazyGhost(static function (object $object) use ($identifier, $entityPersister): void {
+                $entityPersister->loadById($identifier, $object);
+            }, ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE);
+
+            foreach ($identifier as $idField => $value) {
+                $classMetadata->propertyAccessors[$idField]->setValue($proxy, $value);
+            }
+
+            return $proxy;
+        }
+
         $proxyFactory = $this->proxyFactories[$className] ?? $this->getProxyFactory($className);
 
         return $proxyFactory($identifier);
@@ -182,6 +198,10 @@ public function getProxy(string $className, array $identifier): InternalProxy
      */
     public function generateProxyClasses(array $classes, string|null $proxyDir = null): int
     {
+        if ($this->em->getConfiguration()->isNativeLazyObjectsEnabled()) {
+            return 0;
+        }
+
         $generated = 0;
 
         foreach ($classes as $class) {

src/UnitOfWork.php

@@ -2378,7 +2378,11 @@ public function createEntity(string $className, array $data, array &$hints = [])
             }
 
             if ($this->isUninitializedObject($entity)) {
-                $entity->__setInitialized(true);
+                if ($this->em->getConfiguration()->isNativeLazyObjectsEnabled()) {
+                    $class->reflClass->markLazyObjectAsInitialized($entity);
+                } else {
+                    $entity->__setInitialized(true);
+                }
             } else {
                 if (
                     ! isset($hints[Query::HINT_REFRESH])
@@ -3033,6 +3037,13 @@ public function initializeObject(object $obj): void
 
         if ($obj instanceof PersistentCollection) {
             $obj->initialize();
+
+            return;
+        }
+
+        if ($this->em->getConfiguration()->isNativeLazyObjectsEnabled()) {
+            $reflection = $this->em->getClassMetadata($obj::class)->getReflectionClass();
+            $reflection->initializeLazyObject($obj);
         }
     }
 
@@ -3043,6 +3054,10 @@ public function initializeObject(object $obj): void
      */
     public function isUninitializedObject(mixed $obj): bool
     {
+        if ($this->em->getConfiguration()->isNativeLazyObjectsEnabled() && ! ($obj instanceof Collection)) {
+            return $this->em->getClassMetadata($obj::class)->reflClass->isUninitializedLazyObject($obj);
+        }
+
         return $obj instanceof InternalProxy && ! $obj->__isInitialized();
     }
 

tests/Tests/ORM/Functional/BasicFunctionalTest.php

@@ -9,7 +9,6 @@
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\ORMInvalidArgumentException;
 use Doctrine\ORM\PersistentCollection;
-use Doctrine\ORM\Proxy\InternalProxy;
 use Doctrine\ORM\Query;
 use Doctrine\ORM\UnitOfWork;
 use Doctrine\Tests\IterableTester;
@@ -557,7 +556,7 @@ public function testSetToOneAssociationWithGetReference(): void
         $this->_em->persist($article);
         $this->_em->flush();
 
-        self::assertFalse($userRef->__isInitialized());
+        self::assertTrue($this->isUninitializedObject($userRef));
 
         $this->_em->clear();
 
@@ -592,7 +591,7 @@ public function testAddToToManyAssociationWithGetReference(): void
         $this->_em->persist($user);
         $this->_em->flush();
 
-        self::assertFalse($groupRef->__isInitialized());
+        self::assertTrue($this->isUninitializedObject($groupRef));
 
         $this->_em->clear();
 
@@ -940,8 +939,7 @@ public function testManyToOneFetchModeQuery(): void
                              ->setParameter(1, $article->id)
                              ->setFetchMode(CmsArticle::class, 'user', ClassMetadata::FETCH_EAGER)
                              ->getSingleResult();
-        self::assertInstanceOf(InternalProxy::class, $article->user, 'It IS a proxy, ...');
-        self::assertFalse($this->isUninitializedObject($article->user), '...but its initialized!');
+        self::assertFalse($this->isUninitializedObject($article->user));
         $this->assertQueryCount(2);
     }