[Routing] Document route environment condition

routing.rst

@@ -254,6 +254,72 @@ Use the ``methods`` option to restrict the verbs each route should respond to:
 
 .. _routing-matching-expressions:
 
+Matching Environments
+~~~~~~~~~~~~~~~~~~~~~
+
+The ``env`` option can be used to make a route conditional on the
+:ref:`configuration environment <configuration-environments>`, the route will
+only be registered if the environment matches.
+
+.. configuration-block::
+
+    .. code-block:: php-attributes
+
+        // src/Controller/DefaultController.php
+        namespace App\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+        use Symfony\Component\HttpFoundation\Response;
+        use Symfony\Component\Routing\Attribute\Route;
+
+        class DefaultController extends AbstractController
+        {
+            #[Route(
+                '/tools',
+                name: 'tools',
+                env: 'dev',
+            )]
+            public function developerTools(): Response
+            {
+                // ...
+            }
+        }
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        tools:
+            path:       /tools
+            controller: App\Controller\DefaultController::developerTools
+            env:        dev
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="tools" path="/tools" controller="App\Controller\DefaultController::developerTools">
+                <env>dev</env>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use App\Controller\DefaultController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes): void {
+            $routes->add('tools', '/tools')
+                ->controller([DefaultController::class, 'developerTools'])
+                ->env('dev')
+            ;
+        };
+
 Matching Expressions
 ~~~~~~~~~~~~~~~~~~~~