From 3d390bc0532a76a04f104e5160affc91ff138b63 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= <postmaster@greg0ire.fr>
Date: Tue, 17 Jun 2025 20:03:25 +0200
Subject: [PATCH] Deprecate not using native lazy objects on PHP 8.4+

---
 UPGRADE.md                            | 11 ++++++++++
 src/Configuration.php                 | 21 ++++++++++++++++++-
 tests/Tests/ORM/ConfigurationTest.php | 29 +++++++++++++++++++++++++++
 3 files changed, 60 insertions(+), 1 deletion(-)

diff --git a/UPGRADE.md b/UPGRADE.md
index 343cc458472..61e93c7b660 100644
--- a/UPGRADE.md
+++ b/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
diff --git a/src/Configuration.php b/src/Configuration.php
index 953c9cd98dc..ac9bed21a34 100644
--- a/src/Configuration.php
+++ b/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.');
         }
diff --git a/tests/Tests/ORM/ConfigurationTest.php b/tests/Tests/ORM/ConfigurationTest.php
index 269228e72ea..f8a6b16d7f5 100644
--- a/tests/Tests/ORM/ConfigurationTest.php
+++ b/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());
+    }
 }