Deprecate not using native lazy objects on PHP 8.4+

UPGRADE.md

@@ -1,5 +1,16 @@
 # Upgrade to 3.5
 
+## Deprecate not using native lazy objects on PHP 8.4+
+
+Having native lazy objects disabled on PHP 8.4+ is deprecated and will not be
+possible in 4.0.
+
+You can enable them through configuration:
+
+```php
+$config->enableNativeLazyObjects(true);
+```
+
 ## Deprecate methods for configuring no longer configurable features
 
 Since 3.0, lazy ghosts are enabled unconditionally, and so is rejecting ID

src/Configuration.php

@@ -5,6 +5,7 @@
 namespace Doctrine\ORM;
 
 use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Cache\CacheConfiguration;
 use Doctrine\ORM\Exception\InvalidEntityRepository;
 use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
@@ -597,11 +598,29 @@ public function setSchemaIgnoreClasses(array $schemaIgnoreClasses): void
 
     public function isNativeLazyObjectsEnabled(): bool
     {
-        return $this->attributes['nativeLazyObjects'] ?? false;
+        $nativeLazyObjects = $this->attributes['nativeLazyObjects'] ?? false;
+
+        if (! $nativeLazyObjects && PHP_VERSION_ID >= 80400) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/12005',
+                'Not enabling native lazy objects is deprecated and will be impossible in Doctrine ORM 4.0.',
+            );
+        }
+
+        return $nativeLazyObjects;
     }
 
     public function enableNativeLazyObjects(bool $nativeLazyObjects): void
     {
+        if (! $nativeLazyObjects) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/12005',
+                'Disabling native lazy objects is deprecated and will be impossible in Doctrine ORM 4.0.',
+            );
+        }
+
         if (PHP_VERSION_ID < 80400) {
             throw new LogicException('Lazy loading proxies require PHP 8.4 or higher.');
         }

tests/Tests/ORM/ConfigurationTest.php

@@ -4,6 +4,7 @@
 
 namespace Doctrine\Tests\ORM;
 
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use Doctrine\ORM\Cache\CacheConfiguration;
 use Doctrine\ORM\Configuration;
 use Doctrine\ORM\EntityRepository;
@@ -17,6 +18,8 @@
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
 use Doctrine\Tests\Models\DDC753\DDC753CustomRepository;
 use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\Attributes\RequiresPhp;
+use PHPUnit\Framework\Attributes\WithoutErrorHandler;
 use PHPUnit\Framework\TestCase;
 use Psr\Cache\CacheItemPoolInterface;
 
@@ -25,6 +28,8 @@
  */
 class ConfigurationTest extends TestCase
 {
+    use VerifyDeprecations;
+
     private Configuration $configuration;
 
     protected function setUp(): void
@@ -212,4 +217,28 @@ public function testSetGetTypedFieldMapper(): void
         $this->configuration->setTypedFieldMapper($defaultTypedFieldMapper);
         self::assertSame($defaultTypedFieldMapper, $this->configuration->getTypedFieldMapper());
     }
+
+    #[RequiresPhp('8.4')]
+    #[WithoutErrorHandler]
+    public function testDisablingNativeLazyObjectsIsDeprecated(): void
+    {
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/pull/12005');
+
+        $this->configuration->enableNativeLazyObjects(false);
+    }
+
+    #[RequiresPhp('<8.4')]
+    public function testNotEnablingNativeLazyObjectIsFineOnPhpLowerThan84(): void
+    {
+        $this->expectNoDeprecationWithIdentifier('https://github.com/doctrine/orm/pull/12005');
+        self::assertFalse($this->configuration->isNativeLazyObjectsEnabled());
+    }
+
+    #[RequiresPhp('8.4')]
+    #[WithoutErrorHandler]
+    public function testNotEnablingNativeLazyObjectIsDeprecatedOnPhp84(): void
+    {
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/pull/12005');
+        self::assertFalse($this->configuration->isNativeLazyObjectsEnabled());
+    }
 }