[Routing] Construct Route annotations using named arguments

derrabus · derrabus · commit 8b1a3aac3f5a · 2021-02-22T10:07:31.000+01:00
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>
@@ -65,6 +66,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
@@ -5,6 +5,7 @@ CHANGELOG
 -----
 
  * already encoded slashes are not decoded nor double-encoded anymore when generating URLs
+ * Deprecated 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 getValidParametersLegacy
+     */
+    public function testRouteParametersLegacy(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 getValidParametersLegacy(): 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.0",
         "symfony/dependency-injection": "<4.4",
         "symfony/yaml": "<4.4"

Original file line number	Diff line number	Diff line change
`@@ -15,6 +15,7 @@`
`15`	`15`	`* Annotation class for @Route().`
`16`	`16`	`*`
`17`	`17`	`* @Annotation`
	`18`	`+ * @NamedArgumentConstructor`
`18`	`19`	`* @Target({"CLASS", "METHOD"})`
`19`	`20`	`*`
`20`	`21`	`* @author Fabien Potencier <fabien@symfony.com>`
`@@ -65,6 +66,8 @@ public function __construct(`
`65`	`66`	`$data = ['path' => $data];`
`66`	`67`	`} elseif (!\is_array($data)) {`
`67`	`68`	`throw new \TypeError(sprintf('"%s": Argument $data is expected to be a string or array, got "%s".', __METHOD__, get_debug_type($data)));`
	`69`	`+ } elseif ([] !== $data) {`
	`70`	`+ trigger_deprecation('symfony/routing', '5.3', 'Passing an array as first argument to "%s" is deprecated. Use named arguments instead.', __METHOD__);`
`68`	`71`	`}`
`69`	`72`	`if (null !== $path && !\is_string($path) && !\is_array($path)) {`
`70`	`73`	`throw new \TypeError(sprintf('"%s": Argument $path is expected to be a string, array or null, got "%s".', __METHOD__, get_debug_type($path)));`
Original file line number	Diff line number	Diff line change
`@@ -51,7 +51,7 @@ public function testLoadFileWithoutStartTag()`
`51`	`51`
`52`	`52`	`public function testLoadVariadic()`
`53`	`53`	`{`
`54`		`- $route = new Route(['path' => '/path/to/{id}']);`
	`54`	`+ $route = new Route('/path/to/{id}');`
`55`	`55`	`$this->reader->expects($this->once())->method('getClassAnnotation');`
`56`	`56`	`$this->reader->expects($this->once())->method('getMethodAnnotations')`
`57`	`57`	`->willReturn([$route]);`