Add a new report_fields_where_declared config setting

This adds a new config setting `report_fields_where_declared` that makes it easy to opt-in to the new mapping driver mode that was added in Doctrine ORM 2.16 and will be mandatory in ORM 3.0. For details, see doctrine/orm#10455.

I think that since this bundle allows to specify the mapping configuration per entity manager, it would make sense to have this new config setting at the entity manager level as well.

Author: mpdude

DependencyInjection/Configuration.php

@@ -628,6 +628,7 @@ private function getOrmEntityManagersNode(): ArrayNodeDefinition
                     ->arrayNode('schema_ignore_classes')
                         ->prototype('scalar')->end()
                     ->end()
+                    ->scalarNode('report_fields_where_declared')->defaultFalse()->info('Set to "true" to opt-in to the new mapping driver mode that was added in Doctrine ORM 2.16 and will be mandatory in ORM 3.0. See https://github.com/doctrine/orm/pull/10455.')->end()
                 ->end()
                 ->children()
                     ->arrayNode('second_level_cache')

DependencyInjection/DoctrineExtension.php

@@ -823,6 +823,22 @@ protected function loadOrmEntityManagerMappingInformation(array $entityManager,
         $this->loadMappingInformation($entityManager, $container);
         $this->registerMappingDrivers($entityManager, $container);
 
+        $chainDriverDef = $container->getDefinition($this->getObjectManagerElementName($entityManager['name'] . '_metadata_driver'));
+        foreach (array_keys($this->drivers) as $driverType) {
+            $mappingService   = $this->getObjectManagerElementName($entityManager['name'] . '_' . $driverType . '_metadata_driver');
+            $mappingDriverDef = $container->getDefinition($mappingService);
+            $args             = $mappingDriverDef->getArguments();
+            if ($driverType === 'annotation') {
+                $args[2] = $entityManager['report_fields_where_declared'];
+            } elseif ($driverType === 'attribute') {
+                $args[1] = $entityManager['report_fields_where_declared'];
+            } else {
+                continue;
+            }
+
+            $mappingDriverDef->setArguments($args);
+        }
+
         $ormConfigDef->addMethodCall('setEntityNamespaces', [$this->aliasMap]);
     }
 

Resources/doc/configuration.rst

@@ -246,6 +246,8 @@ Configuration Reference
                         class_metadata_factory_name:  Doctrine\ORM\Mapping\ClassMetadataFactory
                         default_repository_class:     Doctrine\ORM\EntityRepository
                         auto_mapping:                 false
+                        # Opt-in to new mapping driver mode as of Doctrine ORM 2.16, https://github.com/doctrine/orm/pull/10455
+                        report_fields_where_declared: false
                         naming_strategy:              doctrine.orm.naming_strategy.default
                         quote_strategy:               doctrine.orm.quote_strategy.default
                         entity_listener_resolver:     ~
@@ -496,6 +498,7 @@ Configuration Reference
                         class-metadata-factory-name="Doctrine\ORM\Mapping\ClassMetadataFactory"
                         default-repository-class="Doctrine\ORM\EntityRepository"
                         auto-mapping="false"
+                        report-fields-where-declared="false"
                         naming-strategy="doctrine.orm.naming_strategy.default"
                         quote-strategy="doctrine.orm.quote_strategy.default"
                         entity-listener-resolver="null"
@@ -652,6 +655,7 @@ the ORM resolves to:
             metadata_cache_driver: ~
             query_cache_driver: ~
             result_cache_driver: ~
+            report_fields_where_declared: false
 
 There are lots of other configuration options that you can use to overwrite
 certain classes, but those are for very advanced use-cases only.

Tests/DependencyInjection/AbstractDoctrineExtensionTest.php

@@ -499,6 +499,7 @@ public function testSingleEntityManagerMultipleMappingBundleDefinitions(): void
             [
                 __DIR__ . DIRECTORY_SEPARATOR . 'Fixtures' . DIRECTORY_SEPARATOR . 'Bundles' . DIRECTORY_SEPARATOR . 'AttributesBundle' . DIRECTORY_SEPARATOR . 'Entity',
             ],
+            false,
         ]);
 
         $ymlDef = $container->getDefinition('doctrine.orm.default_yml_metadata_driver');
@@ -554,6 +555,7 @@ public function testMultipleEntityManagersMappingBundleDefinitions(): void
             [
                 __DIR__ . DIRECTORY_SEPARATOR . 'Fixtures' . DIRECTORY_SEPARATOR . 'Bundles' . DIRECTORY_SEPARATOR . 'AnnotationsBundle' . DIRECTORY_SEPARATOR . 'Entity',
             ],
+            false,
         ]);
 
         $ymlDef = $container->getDefinition('doctrine.orm.em2_yml_metadata_driver');

UPGRADE-2.10.md

@@ -1,6 +1,19 @@
 UPGRADE FROM 2.9 to 2.10
 ========================
 
+Configuration
+-------------
+
+### Preparing for a new `report_fields_where_declared` mapping driver mode
+
+Doctrine ORM 2.16+ makes a change to how the annotations and attribute mapping drivers report fields inherited from parent classes. For details, see https://github.com/doctrine/orm/pull/10455. It will trigger a deprecation notice unless the new mode is activated. In ORM 3.0, the new mode will be the only one.
+
+The new mode ~does not~ should not make a difference for regular, valid use cases, but may lead to `MappingException`s for users with certain configurations that were not meant to be supported by the ORM in the first place. To avoid surprising users (even when their configuration is invalid) during a 2.16 _minor_ version upgrade, the transition to this new mode was implemented as an opt-in. This way, you can try and deal with the change any time you see fit.
+
+In version 2.10+ of this bundle, a new configuration setting `report_fields_where_declared` was added at the entity manager configuration level. Set it to `true` to switch the mapping driver for the corresponding entity manager to the new mode. It is only relevant for mapping configurations using attributes or annotations.
+
+Unless you set it to `true`, Doctrine ORM will emit deprecation messages mentioning this new setting.
+
 ### Deprecations
 
-- `Doctrine\Bundle\DoctrineBundle\EventSubscriber\EventSubscriberInterface` has been deprecated. Use the `#[AsDoctrineListener]` attribute instead.
+- `Doctrine\Bundle\DoctrineBundle\EventSubscriber\EventSubscriberInterface` has been deprecated. Use the `#[AsDoctrineListener]` attribute instead.