From e78d072a7308ddc32e1133ff1b27b11a2ab14afa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= <postmaster@greg0ire.fr>
Date: Fri, 12 Sep 2025 19:15:29 +0200
Subject: [PATCH] Deprecate disable_type_comments

It is a no-op with doctrine/dbal 4.
---
 UPGRADE-2.17.md                               |  5 +++++
 src/DependencyInjection/Configuration.php     | 16 +++++++++++++-
 .../AbstractDoctrineExtensionTestCase.php     | 21 +++++++++++++++++++
 3 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/UPGRADE-2.17.md b/UPGRADE-2.17.md
index b012a0e98..7d505f4c9 100644
--- a/UPGRADE-2.17.md
+++ b/UPGRADE-2.17.md
@@ -9,6 +9,11 @@ Configuration
 This option is a no-op when using `doctrine/orm` 3 and has been conditionally
 deprecated. You should stop using it as soon as you upgrade to Doctrine ORM 3.
 
+### The `doctrine.dbal.connections.some_connection.disable_type_comments` configuration option is deprecated
+
+This option is a no-op when using `doctrine/dbal` 4 and has been conditionally
+deprecated. You should stop using it as soon as you upgrade to Doctrine DBAL 4.
+
 ConnectionFactory::createConnection() signature change
 ------------------------------------------------------
 
diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
index bf9aafe85..19e97bc42 100644
--- a/src/DependencyInjection/Configuration.php
+++ b/src/DependencyInjection/Configuration.php
@@ -4,6 +4,7 @@
 
 namespace Doctrine\Bundle\DoctrineBundle\DependencyInjection;
 
+use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Schema\LegacySchemaManagerFactory;
 use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\EntityManager;
@@ -216,7 +217,20 @@ private function getDbalConnectionsNode(): ArrayNodeDefinition
                     ->defaultValue(true)
                     ->info('Enables collecting schema errors when profiling is enabled')
                 ->end()
-                ->booleanNode('disable_type_comments')->end()
+                ->booleanNode('disable_type_comments')
+                    ->beforeNormalization()
+                        ->ifTrue(static fn ($v): bool => isset($v) && ! method_exists(Connection::class, 'getEventManager'))
+                        ->then(static function ($v) {
+                            Deprecation::trigger(
+                                'doctrine/doctrine-bundle',
+                                'https://github.com/doctrine/DoctrineBundle/pull/2048',
+                                'The "disable_type_comments" configuration key is deprecated when using DBAL 4 and will be removed in DoctrineBundle 3.0.',
+                            );
+
+                            return $v;
+                        })
+                    ->end()
+                ->end()
                 ->scalarNode('server_version')->end()
                 ->integerNode('idle_connection_ttl')->defaultValue(600)->end()
                 ->scalarNode('driver_class')->end()
diff --git a/tests/DependencyInjection/AbstractDoctrineExtensionTestCase.php b/tests/DependencyInjection/AbstractDoctrineExtensionTestCase.php
index 98daa40ed..6832d1618 100644
--- a/tests/DependencyInjection/AbstractDoctrineExtensionTestCase.php
+++ b/tests/DependencyInjection/AbstractDoctrineExtensionTestCase.php
@@ -999,6 +999,27 @@ public function testEnablingReportFieldsWhereDeclaredOnOrm2IsFine(): void
         $this->loadContainer('orm_report_fields');
     }
 
+    #[IgnoreDeprecations]
+    public function testSettingDisableTypeCommentsWithDbal4IsDeprecated(): void
+    {
+        if (method_exists(Connection::class, 'getEventManager')) {
+            self::markTestSkipped('This test requires DBAL 4.');
+        }
+
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/DoctrineBundle/pull/2048');
+        $this->loadContainer(fixture: 'dbal_disable_type_comments', withMinimalOrmConfig: false);
+    }
+
+    public function testSettingDisableTypeCommentsWithDbal3IsFine(): void
+    {
+        if (! method_exists(Connection::class, 'getEventManager')) {
+            self::markTestSkipped('This test requires DBAL 3.');
+        }
+
+        $this->expectNoDeprecationWithIdentifier('https://github.com/doctrine/DoctrineBundle/pull/2048');
+        $this->loadContainer(fixture: 'dbal_disable_type_comments', withMinimalOrmConfig: false);
+    }
+
     public function testResolveTargetEntity(): void
     {
         if (! interface_exists(EntityManagerInterface::class)) {