Deprecate methods related to annotations and yaml

These methods are removed in the next major version.

Author: greg0ire

UPGRADE-2.18.md

@@ -0,0 +1,15 @@
+UPGRADE FROM 2.17 to 2.18
+=========================
+
+DoctrineOrmMappingsPass
+-----------------------
+
+### The `DoctrineOrmMappingsPass::createYamlMappingDriver()` method is deprecated
+
+This method is deprecated with no replacement planned and will be removed in
+DoctrineBundle 3.0.
+
+### The `DoctrineOrmMappingsPass::createAnnotationMappingDriver()` method is deprecated
+
+This method is deprecated with no replacement planned and will be removed in
+DoctrineBundle 3.0.

src/DependencyInjection/Compiler/DoctrineOrmMappingsPass.php

@@ -4,6 +4,7 @@
 
 namespace Doctrine\Bundle\DoctrineBundle\DependencyInjection\Compiler;
 
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Mapping\Driver\AnnotationDriver;
 use Doctrine\ORM\Mapping\Driver\AttributeDriver;
 use Doctrine\ORM\Mapping\Driver\XmlDriver;
@@ -76,6 +77,8 @@ public static function createXmlMappingDriver(array $namespaces, array $managerP
     }
 
     /**
+     * @deprecated no replacement planned
+     *
      * @param string[]     $namespaces        Hashmap of directory path to namespace
      * @param string[]     $managerParameters List of parameters that could which object manager name
      *                                        your bundle uses. This compiler pass will automatically
@@ -90,6 +93,12 @@ public static function createXmlMappingDriver(array $namespaces, array $managerP
      */
     public static function createYamlMappingDriver(array $namespaces, array $managerParameters = [], $enabledParameter = false, array $aliasMap = [])
     {
+        Deprecation::trigger(
+            'doctrine/doctrine-bundle',
+            'https://github.com/doctrine/DoctrineBundle/pull/2088',
+            'The "%s()" method is deprecated and will be removed in DoctrineBundle 3.0.',
+            __METHOD__,
+        );
         $locator = new Definition(SymfonyFileLocator::class, [$namespaces, '.orm.yml']);
         /* @phpstan-ignore class.notFound */
         $driver = new Definition(YamlDriver::class, [$locator]);
@@ -119,6 +128,8 @@ public static function createPhpMappingDriver(array $namespaces, array $managerP
     }
 
     /**
+     * @deprecated no replacement planned
+     *
      * @param string[]     $namespaces                List of namespaces that are handled with annotation mapping
      * @param string[]     $directories               List of directories to look for annotated classes
      * @param string[]     $managerParameters         List of parameters that could which object manager name
@@ -135,6 +146,13 @@ public static function createPhpMappingDriver(array $namespaces, array $managerP
      */
     public static function createAnnotationMappingDriver(array $namespaces, array $directories, array $managerParameters = [], $enabledParameter = false, array $aliasMap = [], bool $reportFieldsWhereDeclared = false)
     {
+        Deprecation::trigger(
+            'doctrine/doctrine-bundle',
+            'https://github.com/doctrine/DoctrineBundle/pull/2088',
+            'The "%s()" method is deprecated and will be removed in DoctrineBundle 3.0.',
+            __METHOD__,
+        );
+
         $reader = new Reference('annotation_reader');
         /* @phpstan-ignore class.notFound */
         $driver = new Definition(AnnotationDriver::class, [$reader, $directories, $reportFieldsWhereDeclared]);

tests/DependencyInjection/Compiler/DoctrineOrmMappingsPassTest.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Bundle\DoctrineBundle\Tests\DependencyInjection\Compiler;
+
+use Doctrine\Bundle\DoctrineBundle\DependencyInjection\Compiler\DoctrineOrmMappingsPass;
+use Doctrine\Bundle\DoctrineBundle\Tests\TestCase;
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
+use PHPUnit\Framework\Attributes\IgnoreDeprecations;
+
+class DoctrineOrmMappingsPassTest extends TestCase
+{
+    use VerifyDeprecations;
+
+    #[IgnoreDeprecations]
+    public function testCreateYamlMappingDriverIsDeprecated(): void
+    {
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/DoctrineBundle/pull/2088');
+
+        DoctrineOrmMappingsPass::createYamlMappingDriver(['/path/to/namespace' => 'App\\Entity']);
+    }
+
+    #[IgnoreDeprecations]
+    public function testCreateAnnotationMappingDriverIsDeprecated(): void
+    {
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/DoctrineBundle/pull/2088');
+
+        DoctrineOrmMappingsPass::createAnnotationMappingDriver(
+            ['App\\Entity'],
+            ['/path/to/entities'],
+        );
+    }
+}