[Routing] Construct Route annotations using named arguments

symfony · fabpot · Feb 25, 2021 · Feb 21, 2021 · Feb 24, 2021 · 29b0f96046b54f9517df7991933d2ffa0d3b33e4
commit 29b0f96046b54f9517df7991933d2ffa0d3b33e4
diff --git a/UPGRADE-5.3.md b/UPGRADE-5.3.md
@@ -68,6 +68,11 @@ PropertyInfo
 
  * Deprecated the `Type::getCollectionKeyType()` and `Type::getCollectionValueType()` methods, use `Type::getCollectionKeyTypes()` and `Type::getCollectionValueTypes()` instead
 
+Routing
+-------
+
+ * Deprecated creating instances of the `Route` annotation class by passing an array of parameters, use named arguments instead
+
 Security
 --------
 

diff --git a/UPGRADE-6.0.md b/UPGRADE-6.0.md
@@ -164,6 +164,7 @@ Routing
  * Removed `RouteCollectionBuilder`.
  * Added argument `$priority` to `RouteCollection::add()`
  * Removed the `RouteCompiler::REGEX_DELIMITER` constant
+ * Removed the `$data` parameter from the constructor of the `Route` annotation class
 
 Security
 --------

diff --git a/composer.json b/composer.json
@@ -123,7 +123,7 @@
         "async-aws/sqs": "^1.0",
         "cache/integration-tests": "dev-master",
         "composer/package-versions-deprecated": "^1.8",
-        "doctrine/annotations": "^1.10.4",
+        "doctrine/annotations": "^1.12",
         "doctrine/cache": "~1.6",
         "doctrine/collections": "~1.0",
         "doctrine/data-fixtures": "^1.1",
@@ -151,6 +151,7 @@
     },
     "conflict": {
         "async-aws/core": "<1.5",
+        "doctrine/annotations": "<1.12",
         "doctrine/dbal": "<2.10",
         "masterminds/html5": "<2.6",
         "phpdocumentor/reflection-docblock": "<3.2.2",

diff --git a/src/Symfony/Component/Routing/Annotation/Route.php b/src/Symfony/Component/Routing/Annotation/Route.php
@@ -15,6 +15,7 @@
  * Annotation class for @Route().
  *
  * @Annotation
+ * @NamedArgumentConstructor
  * @Target({"CLASS", "METHOD"})
  *
  * @author Fabien Potencier <fabien@symfony.com>
@@ -67,6 +68,8 @@ public function __construct(
             $data = ['path' => $data];
         } elseif (!\is_array($data)) {
             throw new \TypeError(sprintf('"%s": Argument $data is expected to be a string or array, got "%s".', __METHOD__, get_debug_type($data)));
+        } elseif ([] !== $data) {
+            trigger_deprecation('symfony/routing', '5.3', 'Passing an array as first argument to "%s" is deprecated. Use named arguments instead.', __METHOD__);
         }
         if (null !== $path && !\is_string($path) && !\is_array($path)) {
             throw new \TypeError(sprintf('"%s": Argument $path is expected to be a string, array or null, got "%s".', __METHOD__, get_debug_type($path)));

diff --git a/src/Symfony/Component/Routing/CHANGELOG.md b/src/Symfony/Component/Routing/CHANGELOG.md
@@ -6,6 +6,7 @@ CHANGELOG
 
  * Already encoded slashes are not decoded nor double-encoded anymore when generating URLs
  * Add support for per-env configuration in loaders
+ * Deprecate creating instances of the `Route` annotation class by passing an array of parameters
 
 5.2.0
 -----

diff --git a/src/Symfony/Component/Routing/Tests/Annotation/RouteTest.php b/src/Symfony/Component/Routing/Tests/Annotation/RouteTest.php
@@ -12,35 +12,56 @@
 namespace Symfony\Component\Routing\Tests\Annotation;
 
 use PHPUnit\Framework\TestCase;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Symfony\Component\Routing\Annotation\Route;
 
 class RouteTest extends TestCase
 {
+    use ExpectDeprecationTrait;
+
+    /**
+     * @group legacy
+     */
     public function testInvalidRouteParameter()
     {
         $this->expectException(\BadMethodCallException::class);
         new Route(['foo' => 'bar']);
     }
 
+    /**
+         * @group legacy
+     */
     public function testTryingToSetLocalesDirectly()
     {
         $this->expectException(\BadMethodCallException::class);
         new Route(['locales' => ['nl' => 'bar']]);
     }
 
     /**
+     * @requires PHP 8
      * @dataProvider getValidParameters
      */
-    public function testRouteParameters($parameter, $value, $getter)
+    public function testRouteParameters(string $parameter, $value, string $getter)
+    {
+        $route = new Route(...[$parameter => $value]);
+        $this->assertEquals($route->$getter(), $value);
+    }
+
+    /**
+     * @group legacy
+     * @dataProvider getLegacyValidParameters
+     */
+    public function testLegacyRouteParameters(string $parameter, $value, string $getter)
     {
+        $this->expectDeprecation('Since symfony/routing 5.3: Passing an array as first argument to "Symfony\Component\Routing\Annotation\Route::__construct" is deprecated. Use named arguments instead.');
+
         $route = new Route([$parameter => $value]);
         $this->assertEquals($route->$getter(), $value);
     }
 
-    public function getValidParameters()
+    public function getValidParameters(): iterable
     {
         return [
-            ['value', '/Blog', 'getPath'],
             ['requirements', ['locale' => 'en'], 'getRequirements'],
             ['options', ['compiler_class' => 'RouteCompiler'], 'getOptions'],
             ['name', 'blog_index', 'getName'],
@@ -49,7 +70,14 @@ public function getValidParameters()
             ['methods', ['GET', 'POST'], 'getMethods'],
             ['host', '{locale}.example.com', 'getHost'],
             ['condition', 'context.getMethod() == "GET"', 'getCondition'],
-            ['value', ['nl' => '/hier', 'en' => '/here'], 'getLocalizedPaths'],
         ];
     }
+
+    public function getLegacyValidParameters(): iterable
+    {
+        yield from $this->getValidParameters();
+
+        yield ['value', '/Blog', 'getPath'];
+        yield ['value', ['nl' => '/hier', 'en' => '/here'], 'getLocalizedPaths'];
+    }
 }
diff --git a/src/Symfony/Component/Routing/Tests/Loader/AnnotationFileLoaderTest.php b/src/Symfony/Component/Routing/Tests/Loader/AnnotationFileLoaderTest.php
@@ -51,7 +51,7 @@ public function testLoadFileWithoutStartTag()
 
     public function testLoadVariadic()
     {
-        $route = new Route(['path' => '/path/to/{id}']);
+        $route = new Route('/path/to/{id}');
         $this->reader->expects($this->once())->method('getClassAnnotation');
         $this->reader->expects($this->once())->method('getMethodAnnotations')
             ->willReturn([$route]);

diff --git a/src/Symfony/Component/Routing/composer.json b/src/Symfony/Component/Routing/composer.json
@@ -26,10 +26,11 @@
         "symfony/yaml": "^4.4|^5.0",
         "symfony/expression-language": "^4.4|^5.0",
         "symfony/dependency-injection": "^4.4|^5.0",
-        "doctrine/annotations": "^1.10.4",
+        "doctrine/annotations": "^1.12",
         "psr/log": "~1.0"
     },
     "conflict": {
+        "doctrine/annotations": "<1.12",
         "symfony/config": "<5.3",
         "symfony/dependency-injection": "<4.4",
         "symfony/yaml": "<4.4"
-Original file line number
+Diff line change
@@ Expand Up / @@ -68,6 +68,11 @@ PropertyInfo @@
      * Deprecated the `Type::getCollectionKeyType()` and `Type::getCollectionValueType()` methods, use `Type::getCollectionKeyTypes()` and `Type::getCollectionValueTypes()` instead
+    Routing
+    -------
+     * Deprecated creating instances of the `Route` annotation class by passing an array of parameters, use named arguments instead
     Security
     --------
@@ Expand Down @@