symfony
diff --git a/‎src/Symfony/Component/Routing/Attribute/DeprecatedAlias.php
Lines changed: 46 additions & 0 deletions b/‎src/Symfony/Component/Routing/Attribute/DeprecatedAlias.php
Lines changed: 46 additions & 0 deletions
diff --git a/‎src/Symfony/Component/Routing/Attribute/Route.php
Lines changed: 26 additions & 30 deletions b/‎src/Symfony/Component/Routing/Attribute/Route.php
Lines changed: 26 additions & 30 deletions
diff --git a/‎src/Symfony/Component/Routing/Loader/AttributeClassLoader.php
Lines changed: 13 additions & 3 deletions b/‎src/Symfony/Component/Routing/Loader/AttributeClassLoader.php
Lines changed: 13 additions & 3 deletions
diff --git a/‎src/Symfony/Component/Routing/Tests/Attribute/RouteTest.php
Lines changed: 1 addition & 10 deletions b/‎src/Symfony/Component/Routing/Tests/Attribute/RouteTest.php
Lines changed: 1 addition & 10 deletions
diff --git a/‎src/Symfony/Component/Routing/Tests/Fixtures/AttributeFixtures/DeprecatedAliasCustomMessageRouteController.php
Lines changed: 24 additions & 0 deletions b/‎src/Symfony/Component/Routing/Tests/Fixtures/AttributeFixtures/DeprecatedAliasCustomMessageRouteController.php
Lines changed: 24 additions & 0 deletions
diff --git a/‎src/Symfony/Component/Routing/Tests/Fixtures/AttributeFixtures/DeprecatedAliasRouteController.php
Lines changed: 24 additions & 0 deletions b/‎src/Symfony/Component/Routing/Tests/Fixtures/AttributeFixtures/DeprecatedAliasRouteController.php
Lines changed: 24 additions & 0 deletions
diff --git a/‎src/Symfony/Component/Routing/Tests/Fixtures/AttributeFixtures/MultipleDeprecatedAliasRouteController.php
Lines changed: 28 additions & 0 deletions b/‎src/Symfony/Component/Routing/Tests/Fixtures/AttributeFixtures/MultipleDeprecatedAliasRouteController.php
Lines changed: 28 additions & 0 deletions
diff --git a/‎src/Symfony/Component/Routing/Tests/Loader/AttributeClassLoaderTest.php
Lines changed: 69 additions & 0 deletions b/‎src/Symfony/Component/Routing/Tests/Loader/AttributeClassLoaderTest.php
Lines changed: 69 additions & 0 deletions
@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Routing\Attribute;
+
+/**
+ * This class is meant to be used in {@see Route} to define an alias for a route.
+ */
+class DeprecatedAlias
+{
+    public function __construct(
+        private string $aliasName,
+        private string $package,
+        private string $version,
+        private string $message = '',
+    ) {
+    }
+
+    public function getMessage(): string
+    {
+        return $this->message;
+    }
+
+    public function getAliasName(): string
+    {
+        return $this->aliasName;
+    }
+
+    public function getPackage(): string
+    {
+        return $this->package;
+    }
+
+    public function getVersion(): string
+    {
+        return $this->version;
+    }
+}
@@ -24,25 +24,28 @@ class Route
     private array $localizedPaths = [];
     private array $methods;
     private array $schemes;
-    private array $aliases;
+    /**
+     * @var DeprecatedAlias[]|string[]
+     */
+    private array $aliases = [];
 
     /**
-     * @param string|array<string,string>|null $path         The route path (i.e. "/user/login")
-     * @param string|null                      $name         The route name (i.e. "app_user_login")
-     * @param array<string|\Stringable>        $requirements Requirements for the route attributes, @see https://symfony.com/doc/current/routing.html#parameters-validation
-     * @param array<string, mixed>             $options      Options for the route (i.e. ['prefix' => '/api'])
-     * @param array<string, mixed>             $defaults     Default values for the route attributes and query parameters
-     * @param string|null                      $host         The host for which this route should be active (i.e. "localhost")
-     * @param string|string[]                  $methods      The list of HTTP methods allowed by this route
-     * @param string|string[]                  $schemes      The list of schemes allowed by this route (i.e. "https")
-     * @param string|null                      $condition    An expression that must evaluate to true for the route to be matched, @see https://symfony.com/doc/current/routing.html#matching-expressions
-     * @param int|null                         $priority     The priority of the route if multiple ones are defined for the same path
-     * @param string|null                      $locale       The locale accepted by the route
-     * @param string|null                      $format       The format returned by the route (i.e. "json", "xml")
-     * @param bool|null                        $utf8         Whether the route accepts UTF-8 in its parameters
-     * @param bool|null                        $stateless    Whether the route is defined as stateless or stateful, @see https://symfony.com/doc/current/routing.html#stateless-routes
-     * @param string|null                      $env          The env in which the route is defined (i.e. "dev", "test", "prod")
-     * @param string|string[]                  $alias        The list of aliases for this route
+     * @param string|array<string,string>|null                  $path         The route path (i.e. "/user/login")
+     * @param string|null                                       $name         The route name (i.e. "app_user_login")
+     * @param array<string|\Stringable>                         $requirements Requirements for the route attributes, @see https://symfony.com/doc/current/routing.html#parameters-validation
+     * @param array<string, mixed>                              $options      Options for the route (i.e. ['prefix' => '/api'])
+     * @param array<string, mixed>                              $defaults     Default values for the route attributes and query parameters
+     * @param string|null                                       $host         The host for which this route should be active (i.e. "localhost")
+     * @param string|string[]                                   $methods      The list of HTTP methods allowed by this route
+     * @param string|string[]                                   $schemes      The list of schemes allowed by this route (i.e. "https")
+     * @param string|null                                       $condition    An expression that must evaluate to true for the route to be matched, @see https://symfony.com/doc/current/routing.html#matching-expressions
+     * @param int|null                                          $priority     The priority of the route if multiple ones are defined for the same path
+     * @param string|null                                       $locale       The locale accepted by the route
+     * @param string|null                                       $format       The format returned by the route (i.e. "json", "xml")
+     * @param bool|null                                         $utf8         Whether the route accepts UTF-8 in its parameters
+     * @param bool|null                                         $stateless    Whether the route is defined as stateless or stateful, @see https://symfony.com/doc/current/routing.html#stateless-routes
+     * @param string|null                                       $env          The env in which the route is defined (i.e. "dev", "test", "prod")
+     * @param string|string[]|DeprecatedAlias|DeprecatedAlias[] $alias        The list of aliases for this route
      */
     public function __construct(
         string|array|null $path = null,
@@ -60,7 +63,7 @@ public function __construct(
         ?bool $utf8 = null,
         ?bool $stateless = null,
         private ?string $env = null,
-        array|string $alias = [],
+        string|DeprecatedAlias|array $alias = [],
     ) {
         if (\is_array($path)) {
             $this->localizedPaths = $path;
@@ -209,28 +212,21 @@ public function getEnv(): ?string
     }
 
     /**
-     * @return string[]
+     * @return string[]|DeprecatedAlias[]
      */
     public function getAliases(): array
     {
         return $this->aliases;
     }
 
     /**
-     * @param string[]|string $aliases
+     * @param string|DeprecatedAlias|string[]|DeprecatedAlias[] $aliases
      *
      * @throws InvalidArgumentException if the "alias" argument is not a string or an array of strings
      */
-    public function setAliases(array|string $aliases): void
-    {
-        if (\is_array($aliases)) {
-            foreach ($aliases as $a) {
-                if (!\is_string($a)) {
-                    throw new InvalidArgumentException(\sprintf('The "alias" argument of the Route attribute must be a string or an array of strings. Got "%s".', get_debug_type($a)));
-                }
-            }
-        }
-        $this->aliases = (array) $aliases;
+    public function setAliases(string|DeprecatedAlias|array $aliases): void
+    {
+        $this->aliases = $aliases instanceof DeprecatedAlias || \is_string($aliases) ? [$aliases] : $aliases;
     }
 }
 
 
@@ -111,7 +111,7 @@ public function load(mixed $class, ?string $type = null): RouteCollection
         if (!$class->hasMethod('__invoke')) {
             foreach ($this->getAttributes($class) as $attr) {
                 if ($attr->getAliases()) {
-                    throw new \InvalidArgumentException(\sprintf('Route aliases cannot be used on non-invokable class "%s".', $class->name));
+                    throw new \InvalidArgumentException(\sprintf('Route aliases cannot be used on non-invokable class "%s".', $class->getName()));
                 }
             }
         }
@@ -239,8 +239,18 @@ protected function addRoute(RouteCollection $collection, object $attr, array $gl
             } else {
                 $collection->add($name, $route, $priority);
             }
-            foreach ($attr->getAliases() as $alias) {
-                $collection->addAlias($alias, $name);
+            foreach ($attr->getAliases() as $aliasAttribute) {
+                if (\is_string($aliasAttribute)) {
+                    $collection->addAlias($aliasAttribute, $name);
+                    continue;
+                }
+
+                $alias = $collection->addAlias($aliasAttribute->getAliasName(), $name);
+                $alias->setDeprecated(
+                    $aliasAttribute-><
1241
span class=pl-en>getPackage(),
+                    $aliasAttribute->getVersion(),
+                    $aliasAttribute->getMessage()
+                );
             }
         }
     }
 
@@ -9,11 +9,10 @@
  * file that was distributed with this source code.
  */
 
-namespace Symfony\Component\Routing\Tests\Annotation;
+namespace Symfony\Component\Routing\Tests\Attribute;
 
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Routing\Attribute\Route;
-use Symfony\Component\Routing\Exception\InvalidArgumentException;
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\FooController;
 
 class RouteTest extends TestCase
@@ -28,14 +27,6 @@ public function testLoadFromAttribute(string $methodName, string $getter, mixed
         $this->assertEquals($route->$getter(), $expectedReturn);
     }
 
-    public function testAliasIsAnArrayOfString()
-    {
-        $this->expectException(InvalidArgumentException::class);
-        $this->expectExceptionMessage('The "alias" argument of the Route attribute must be a string or an array of strings. Got "stdClass".');
-
-        new Route('/hello', alias: ['alias', new \stdClass()]);
-    }
-
     public static function getValidParameters(): iterable
     {
         return [
 
@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures;
+
+use Symfony\Component\Routing\Attribute\DeprecatedAlias;
+use Symfony\Component\Routing\Attribute\Route;
+
+class DeprecatedAliasCustomMessageRouteController
+{
+
+    #[Route('/path', name: 'action_with_deprecated_alias', alias: new DeprecatedAlias('my_other_alias_deprecated', 'MyBundleFixture', '1.0', message: '%alias_id% alias is deprecated.'))]
+    public function action()
+    {
+    }
+}
@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures;
+
+use Symfony\Component\Routing\Attribute\DeprecatedAlias;
+use Symfony\Component\Routing\Attribute\Route;
+
+class DeprecatedAliasRouteController
+{
+
+    #[Route('/path', name: 'action_with_deprecated_alias', alias: new DeprecatedAlias('my_other_alias_deprecated', 'MyBundleFixture', '1.0'))]
+    public function action()
+    {
+    }
+}
@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures;
+
+use Symfony\Component\Routing\Attribute\DeprecatedAlias;
+use Symfony\Component\Routing\Attribute\Route;
+
+class MultipleDeprecatedAliasRouteController
+{
+
+    #[Route('/path', name: 'action_with_multiple_deprecated_alias', alias: [
+        new DeprecatedAlias('my_first_alias_deprecated', 'MyFirstBundleFixture', '1.0'),
+        new DeprecatedAlias('my_second_alias_deprecated', 'MySecondBundleFixture', '2.0'),
+        new DeprecatedAlias('my_third_alias_deprecated', 'SurprisedThirdBundleFixture', '3.0'),
+    ])]
+    public function action()
+    {
+    }
+}
@@ -21,6 +21,8 @@
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\AliasRouteController;
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\BazClass;
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\DefaultValueController;
+use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\DeprecatedAliasCustomMessageRouteController;
+use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\DeprecatedAliasRouteController;
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\EncodingClass;
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\ExplicitLocalizedActionPathController;
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\ExtendedRouteOnClassController;
@@ -38,6 +40,7 @@
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\MethodActionControllers;
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\MethodsAndSchemes;
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\MissingRouteNameController;
+use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\MultipleDeprecatedAliasRouteController;
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\NothingButNameController;
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\PrefixedActionLocalizedRouteController;
 use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\PrefixedActionPathController;
@@ -395,4 +398,70 @@ public function testAliasesOnInvokableClass()
         $this->assertEquals(new Alias('invokable_path'), $routes->getAlias('alias'));
         $this->assertEquals(new Alias('invokable_path'), $routes
C2EE
->getAlias('completely_different_name'));
     }
+
+    public function testDeprecatedAlias()
+    {
+        $routes = $this->loader->load(DeprecatedAliasRouteController::class);
+        $route = $routes->get('action_with_deprecated_alias');
+        $expected = (new Alias('action_with_deprecated_alias'))
+            ->setDeprecated(
+                'MyBundleFixture',
+                '1.0',
+                'The "%alias_id%" route alias is deprecated. You should stop using it, as it will be removed in the future.'
+            );
+        $actual = $routes->getAlias('my_other_alias_deprecated');
+        $this->assertCount(1, $routes);
+        $this->assertSame('/path', $route->getPath());
+        $this->assertEquals($expected, $actual);
+    }
+
+    public function testDeprecatedAliasWithCustomMessage()
+    {
+        $routes = $this->loader->load(DeprecatedAliasCustomMessageRouteController::class);
+        $route = $routes->get('action_with_deprecated_alias');
+        $expected = (new Alias('action_with_deprecated_alias'))
+            ->setDeprecated(
+                'MyBundleFixture',
+                '1.0',
+                '%alias_id% alias is deprecated.'
+            );
+        $actual = $routes->getAlias('my_other_alias_deprecated');
+        $this->assertCount(1, $routes);
+        $this->assertSame('/path', $route->getPath());
+        $this->assertEquals($expected, $actual);
+    }
+
+    public function testMultipleDeprecatedAlias()
+    {
+        $routes = $this->loader->load(MultipleDeprecatedAliasRouteController::class);
+        $route = $routes->get('action_with_multiple_deprecated_alias');
+        $this->assertCount(1, $routes);
+        $this->assertSame('/path', $route->getPath());
+
+        $dataset = [
+            'my_first_alias_deprecated' => [
+                'package' => 'MyFirstBundleFixture',
+                'version' => '1.0',
+            ],
+            'my_second_alias_deprecated' => [
+                'package' => 'MySecondBundleFixture',
+                'version' => '2.0',
+            ],
+            'my_third_alias_deprecated' => [
+                'package' => 'SurprisedThirdBundleFixture',
+                'version' => '3.0',
+            ],
+        ];
+
+        foreach ($dataset as $aliasName => $aliasData) {
+            $expected = (new Alias('action_with_multiple_deprecated_alias'))
+                ->setDeprecated(
+                    $aliasData['package'],
+                    $aliasData['version'],
+                    'The "%alias_id%" route alias is deprecated. You should stop using it, as it will be removed in the future.'
+                );
+            $actual = $routes->getAlias($aliasName);
+            $this->assertEquals($expected, $actual);
+        }
+    }
 }