feature symfony#61358 [Routing] allow setting multiple envs in #[Route] attribute (santysisi)

This PR was merged into the 7.4 branch.

Discussion
----------

[Routing] allow setting multiple envs in `#[Route]` attribute

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | yes
| Issues        | Fix symfony#61344
| License       | MIT

## Summary

This PR enhances the `Symfony\Component\Routing\Attribute\Route` attribute by allowing the `env` parameter to accept an array of environment names. This change enables defining a single route that is conditionally available in multiple environments without duplicating route definitions.

## Before

To make a route available in both `dev` and `test` environments, two separate route attributes were needed:

```php
#[Route('/test', name: 'test', env: 'dev')]
#[Route('/test', name: 'test-testing', env: 'test')]
```

## After

Now, the same can be achieved with a single attribute by passing an array:

```php
#[Route('/test', name: 'test', env: ['dev', 'test'])]
```

Commits
-------

525ec95 [Routing] allow setting multiple envs in `#[Route]` attribute

Author: nicolas-grekas

UPGRADE-7.4.md

@@ -64,6 +64,11 @@ Mime
 
  * Deprecate implementing `__sleep/wakeup()` on `AbstractPart` implementations; use `__(un)serialize()` instead
 
+Routing
+-------
+
+ * Deprecate `getEnv()` and `setEnv()` methods of the `Symfony\Component\Routing\Attribute\Route` class in favor of the plurialized `getEnvs()` and `setEnvs()` methods
+
 Security
 --------
 

src/Symfony/Component/Routing/Attribute/Route.php

@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\Routing\Attribute;
 
+use Symfony\Component\Routing\Exception\LogicException;
+
 /**
  * @author Fabien Potencier <fabien@symfony.com>
  * @author Alexander M. Turek <me@derrabus.de>
@@ -21,6 +23,8 @@ class Route
     private ?string $path = null;
     private array $localizedPaths = [];
     private array $methods;
+    /** @var string[] */
+    private array $env;
     private array $schemes;
     /**
      * @var (string|DeprecatedAlias)[]
@@ -42,7 +46,7 @@ class 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[]|null                              $env          The env(s) in which the route is defined (i.e. "dev", "test", "prod", ["dev", "test"])
      * @param string|DeprecatedAlias|(string|DeprecatedAlias)[] $alias        The list of aliases for this route
      */
     public function __construct(
@@ -60,7 +64,7 @@ public function __construct(
         ?string $format = null,
         ?bool $utf8 = null,
         ?bool $stateless = null,
-        private ?string $env = null,
+        string|array|null $env = null,
         string|DeprecatedAlias|array $alias = [],
     ) {
         if (\is_array($path)) {
@@ -71,6 +75,7 @@ public function __construct(
         $this->setMethods($methods);
         $this->setSchemes($schemes);
         $this->setAliases($alias);
+        $this->setEnvs((array) $env);
 
         if (null !== $locale) {
             $this->defaults['_locale'] = $locale;
@@ -199,12 +204,37 @@ public function getPriority(): ?int
         return $this->priority;
     }
 
+    /**
+     * @deprecated since Symfony 7.4, use the {@see setEnvs()} method instead
+     */
     public function setEnv(?string $env): void
     {
-        $this->env = $env;
+        trigger_deprecation('symfony/routing', '7.4', 'The "%s()" method is deprecated, use "setEnvs()" instead.', __METHOD__);
+        $this->env = (array) $env;
     }
 
+    /**
+     * @deprecated since Symfony 7.4, use {@see getEnvs()} method instead
+     */
     public function getEnv(): ?string
+    {
+        trigger_deprecation('symfony/routing', '7.4', 'The "%s()" method is deprecated, use "getEnvs()" instead.', __METHOD__);
+        if (!$this->env) {
+            return null;
+        }
+        if (\count($this->env) > 1) {
+            throw new LogicException(\sprintf('The "env" property has %d environments. Use "getEnvs()" to get all of them.', \count($this->env)));
+        }
+
+        return $this->env[0];
+    }
+
+    public function setEnvs(array|string $env): void
+    {
+        $this->env = (array) $env;
+    }
+
+    public function getEnvs(): array
     {
         return $this->env;
     }

src/Symfony/Component/Routing/CHANGELOG.md

@@ -5,6 +5,7 @@ CHANGELOG
 ---
 
  * Allow query-specific parameters in `UrlGenerator` using `_query`
+ * Add support of multiple env names in the  `Symfony\Component\Routing\Attribute\Route` attribute
 
 7.3
 ---

src/Symfony/Component/Routing/Loader/AttributeClassLoader.php

@@ -105,7 +105,7 @@ public function load(mixed $class, ?string $type = null): RouteCollection
         $globals = $this->getGlobals($class);
         $collection = new RouteCollection();
         $collection->addResource(new FileResource($class->getFileName()));
-        if ($globals['env'] && $this->env !== $globals['env']) {
+        if ($globals['env'] && !\in_array($this->env, $globals['env'], true)) {
             return $collection;
         }
         $fqcnAlias = false;
@@ -161,7 +161,7 @@ public function load(mixed $class, ?string $type = null): RouteCollection
      */
     protected function addRoute(RouteCollection $collection, object $attr, array $globals, \ReflectionClass $class, \ReflectionMethod $method): void
     {
-        if ($attr->getEnv() && $attr->getEnv() !== $this->env) {
+        if ($attr->getEnvs() && !\in_array($this->env, $attr->getEnvs(), true)) {
             return;
         }
 
@@ -338,7 +338,7 @@ protected function getGlobals(\ReflectionClass $class): array
             }
 
             $globals['priority'] = $attr->getPriority() ?? 0;
-            $globals['env'] = $attr->getEnv();
+            $globals['env'] = $attr->getEnvs();
 
             foreach ($globals['requirements'] as $placeholder => $requirement) {
                 if (\is_int($placeholder)) {

src/Symfony/Component/Routing/Tests/Fixtures/AttributeFixtures/RouteWithEnv.php

@@ -16,4 +16,19 @@ public function action()
     public function action2()
     {
     }
+
+    #[Route(path: '/path3', name: 'action3', env: ['some-other-env', 'some-other-env-two'])]
+    public function action3()
+    {
+    }
+
+    #[Route(path: '/path4', name: 'action4', env: null)]
+    public function action4()
+    {
+    }
+
+    #[Route(path: '/path5', name: 'action5', env: ['some-other-env', 'some-env'])]
+    public function action5()
+    {
+    }
 }

src/Symfony/Component/Routing/Tests/Loader/AttributeClassLoaderTest.php

@@ -330,8 +330,10 @@ public function testWhenEnv()
 
         $this->setUp('some-env');
         $routes = $this->loader->load(RouteWithEnv::class);
-        $this->assertCount(1, $routes);
+        $this->assertCount(3, $routes);
         $this->assertSame('/path', $routes->get('action')->getPath());
+        $this->assertSame('/path4', $routes->get('action4')->getPath());
+        $this->assertSame('/path5', $routes->get('action5')->getPath());
     }
 
     public function testMethodsAndSchemes()