Merge pull request #10161 from greg0ire/deprecate-mapping-drivers

Make the mapping driver deprecations more obvious

Author: greg0ire

UPGRADE.md

@@ -5,6 +5,10 @@
 Please switch to one of the other mapping drivers. Native attributes which PHP
 supports since version 8.0 are probably your best option.
 
+As a consequence, the following methods are deprecated:
+- `ORMSetup::createAnnotationMetadataConfiguration`
+- `ORMSetup::createDefaultAnnotationDriver`
+
 ## Deprecated `Doctrine\ORM\Proxy\Proxy` interface.
 
 Use `Doctrine\Persistence\Proxy` instead to check whether proxies are initialized.

docs/en/reference/advanced-configuration.rst

@@ -114,11 +114,13 @@ classes.
 There are currently 5 available implementations:
 
 
--  ``Doctrine\ORM\Mapping\Driver\AnnotationDriver``
 -  ``Doctrine\ORM\Mapping\Driver\AttributeDriver``
 -  ``Doctrine\ORM\Mapping\Driver\XmlDriver``
--  ``Doctrine\ORM\Mapping\Driver\YamlDriver``
 -  ``Doctrine\ORM\Mapping\Driver\DriverChain``
+-  ``Doctrine\ORM\Mapping\Driver\AnnotationDriver`` (deprecated and will
+  be removed in ``doctrine/orm`` 3.0)
+-  ``Doctrine\ORM\Mapping\Driver\YamlDriver`` (deprecated and will be
+   removed in ``doctrine/orm`` 3.0)
 
 Throughout the most part of this manual the AttributeDriver is
 used in the examples. For information on the usage of the

docs/en/reference/basic-mapping.rst

@@ -45,9 +45,10 @@ Doctrine provides several different ways to specify object-relational
 mapping metadata:
 
 -  :doc:`Attributes <attributes-reference>`
--  :doc:`Docblock Annotations <annotations-reference>`
 -  :doc:`XML <xml-mapping>`
 -  :doc:`PHP code <php-mapping>`
+-  :doc:`Docblock Annotations <annotations-reference>` (deprecated and
+  will be removed in ``doctrine/orm`` 3.0)
 -  :doc:`YAML <yaml-mapping>` (deprecated and will be removed in ``doctrine/orm`` 3.0.)
 
 This manual will usually show mapping metadata via attributes, though

docs/en/reference/metadata-drivers.rst

@@ -13,11 +13,16 @@ metadata:
 
 
 -  **XML files** (XmlDriver)
--  **Class DocBlock Annotations** (AnnotationDriver)
 -  **Attributes** (AttributeDriver)
--  **YAML files** (YamlDriver)
 -  **PHP Code in files or static functions** (PhpDriver)
 
+There are also two deprecated ways to do this:
+
+-  **Class DocBlock Annotations** (AnnotationDriver)
+-  **YAML files** (YamlDriver)
+
+They will be removed in 3.0, make sure to avoid them.
+
 Something important to note about the above drivers is they are all
 an intermediate step to the same end result. The mapping
 information is populated to ``Doctrine\ORM\Mapping\ClassMetadata``
@@ -40,8 +45,9 @@ an entity.
 
 
 If you want to use one of the included core metadata drivers you need to
-configure it. If you pick the annotation driver, you will additionally
-need to install ``doctrine/annotations``. All the drivers are in the
+configure it. If you pick the annotation driver despite it being
+deprecated, you will additionally need to install
+``doctrine/annotations``. All the drivers are in the
 ``Doctrine\ORM\Mapping\Driver`` namespace:
 
 .. code-block:: php
@@ -120,17 +126,17 @@ the ``FileDriver`` implementation for you to extend from:
          * {@inheritdoc}
          */
         protected $_fileExtension = '.dcm.ext';
-    
+
         /**
          * {@inheritdoc}
          */
         public function loadMetadataForClass($className, ClassMetadata $metadata)
         {
             $data = $this->_loadMappingFile($file);
-    
+
             // populate ClassMetadata instance from $data
         }
-    
+
         /**
          * {@inheritdoc}
          */
@@ -198,5 +204,3 @@ iterate over them:
     foreach ($class->fieldMappings as $fieldMapping) {
         echo $fieldMapping['fieldName'] . "\n";
     }
-
-

lib/Doctrine/ORM/Mapping/Driver/AnnotationDriver.php

@@ -64,7 +64,7 @@ public function __construct($reader, $paths = null)
     {
         Deprecation::trigger(
             'doctrine/orm',
-            'https://github.com/doctrine/orm/issues/10096',
+            'https://github.com/doctrine/orm/issues/10098',
             'The annotation mapping driver is deprecated and will be removed in Doctrine ORM 3.0, please migrate to the attribute or XML driver.'
         );
         $this->reader = $reader;

lib/Doctrine/ORM/ORMSetup.php

@@ -31,6 +31,8 @@ final class ORMSetup
     /**
      * Creates a configuration with an annotation metadata driver.
      *
+     * @deprecated Use another mapping driver.
+     *
      * @param string[] $paths
      */
     public static function createAnnotationMetadataConfiguration(
@@ -39,6 +41,12 @@ public static function createAnnotationMetadataConfiguration(
         ?string $proxyDir = null,
         ?CacheItemPoolInterface $cache = null
     ): Configuration {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/10098',
+            '%s is deprecated and will be removed in Doctrine ORM 3.0',
+            __METHOD__
+        );
         $config = self::createConfiguration($isDevMode, $proxyDir, $cache);
         $config->setMetadataDriverImpl(self::createDefaultAnnotationDriver($paths));
 
@@ -48,12 +56,20 @@ public static function createAnnotationMetadataConfiguration(
     /**
      * Adds a new default annotation driver with a correctly configured annotation reader.
      *
+     * @deprecated Use another mapping driver.
+     *
      * @param string[] $paths
      */
     public static function createDefaultAnnotationDriver(
         array $paths = [],
         ?CacheItemPoolInterface $cache = null
     ): AnnotationDriver {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/10098',
+            '%s is deprecated and will be removed in Doctrine ORM 3.0',
+            __METHOD__
+        );
         if (! class_exists(AnnotationReader::class)) {
             throw new LogicException(sprintf(
                 'The annotation metadata driver cannot be enabled because the "doctrine/annotations" library'

psalm.xml

@@ -79,6 +79,7 @@
                 <referencedMethod name="Doctrine\ORM\Configuration::newDefaultAnnotationDriver"/>
                 <referencedMethod name="Doctrine\ORM\Id\AbstractIdGenerator::generate"/>
                 <referencedMethod name="Doctrine\ORM\ORMInvalidArgumentException::invalidEntityName"/>
+                <referencedMethod name="Doctrine\ORM\ORMSetup::createDefaultAnnotationDriver"/>
                 <referencedMethod name="Doctrine\ORM\Query\TreeWalkerAdapter::_getQueryComponents"/>
                 <file name="lib/Doctrine/ORM/Query/TreeWalkerChain.php"/>
             </errorLevel>