feature #16313 [Configuration] Multiple environments in a single file (MaximePinot)

This PR was squashed before being merged into the 5.3 branch.

Discussion
----------

[Configuration] Multiple environments in a single file

As `@BafS`  mentioned in the Symfony slack, the new Symfony 5.3 feature about defining options for different environments in a single file is not documented, apart from [this blog post](https://symfony.com/blog/new-in-symfony-5-3-configure-multiple-environments-in-a-single-file). I could not find anything about it in the documentation either.

Here is a proposal to include the blog post in the documentation.

I put it in a `tip` section. Perhaps it is worth putting it in a new section below  `Configuration Environments` (or as a subsection) ? 🤔

Commits
-------

dbc99b8 Move #[When] attribute to Service Container docs
61f5000 [Configuration] Multiple environments in a single file

Author: wouterj

configuration.rst

@@ -410,6 +410,88 @@ In reality, each environment differs only somewhat from others. This means that
 all environments share a large base of common configuration, which is put in
 files directly in the ``config/packages/`` directory.
 
+.. tip::
+
+    .. versionadded:: 5.3
+
+        The ability to defined different environments in a single file was
+        introduced in Symfony 5.3.
+
+    You can also define options for different environments in a single
+    configuration file using the special ``when`` keyword:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/webpack_encore.yaml
+            webpack_encore:
+                # ...
+                output_path: '%kernel.project_dir%/public/build'
+                strict_mode: true
+                cache: false
+
+            # cache is enabled only in the "prod" environment
+            when@prod:
+                webpack_encore:
+                    cache: true
+
+            # disable strict mode only in the "test" environment
+            when@test:
+                webpack_encore:
+                    strict_mode: false
+
+        .. code-block:: xml
+
+            <!-- config/packages/webpack_encore.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                <webpack-encore:config
+                    output-path="%kernel.project_dir%/public/build"
+                    strict-mode="true"
+                    cache="false"
+                />
+
+                <!-- cache is enabled only in the "test" environment -->
+                <when env="prod">
+                    <webpack-encore:config cache="true"/>
+                </when>
+
+                <!-- disable strict mode only in the "test" environment -->
+                <when env="test">
+                    <webpack-encore:config strict-mode="false"/>
+                </when>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/framework.php
+            use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+            use Symfony\Config\WebpackEncoreConfig;
+
+            return static function (WebpackEncoreConfig $webpackEncore, ContainerConfigurator $container) {
+                $webpackEncore
+                    ->outputPath('%kernel.project_dir%/public/build')
+                    ->strictMode(true)
+                    ->cache(false)
+                ;
+
+                // cache is enabled only in the "prod" environment
+                if ('prod' === $container->env()) {
+                    $webpackEncore->cache(true);
+                }
+
+                // disable strict mode only in the "test" environment
+                if ('test' === $container->env()) {
+                    $webpackEncore->strictMode(false);
+                }
+            };
+
 .. seealso::
 
     See the ``configureContainer()`` method of

service_container.rst

@@ -222,6 +222,35 @@ each time you ask for it.
     If you'd prefer to manually wire your service, that's totally possible: see
     :ref:`services-explicitly-configure-wire-services`.
 
+Limiting Services to a specific Symfony Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 5.3
+
+    The ``#[When]`` attribute was introduced in Symfony 5.3.
+
+If you are using PHP 8.0 or later, you can use the ``#[When]`` PHP
+attribute to only register the class as a service in some environments::
+
+    use Symfony\Component\DependencyInjection\Attribute\When;
+
+    // SomeClass is only registered in the "dev" environment
+
+    #[When(env: 'dev')]
+    class SomeClass
+    {
+        // ...
+    }
+
+    // you can also apply more than one When attribute to the same class
+
+    #[When(env: 'dev')]
+    #[When(env: 'test')]
+    class AnotherClass
+    {
+        // ...
+    }
+
 .. _services-constructor-injection:
 
 Injecting Services/Config into a Service