[DI] Document %env(...)% dynamic parameters

Author: nicolas-grekas

configuration/external_parameters.rst

@@ -10,20 +10,57 @@ to store certain credentials outside of your project code. Database configuratio
 is one such example. The flexibility of the Symfony service container allows
 you to easily do this.
 
-Environment Variables
----------------------
+Environment Variables as Default Parameter Values
+-------------------------------------------------
 
-Symfony will grab any environment variable prefixed with ``SYMFONY__`` and
-set it as a parameter in the service container. Some transformations are
-applied to the resulting parameter name:
+Any parameters used in the service container can have their default values be set
+using environment variables prefixed with ``SYMFONY__`` and where dots in
+parameter names are replaced by double underscores.
 
-* ``SYMFONY__`` prefix is removed;
-* Parameter name is lowercased;
-* Double underscores are replaced with a period, as a period is not
-  a valid character in an environment variable name.
+For example, if you have a configuration that reads as such:
 
-For example, if you're using Apache, environment variables can be set using
-the following ``VirtualHost`` configuration:
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        doctrine:
+            dbal:
+                driver:   pdo_mysql
+                dbname:   symfony_project
+                user:     '%database.user%'
+                password: '%database.password%'
+
+    .. code-block:: xml
+
+        <!-- xmlns:doctrine="http://symfony.com/schema/dic/doctrine" -->
+        <!-- xsi:schemaLocation="http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd"> -->
+
+        <doctrine:config>
+            <doctrine:dbal
+                driver="pdo_mysql"
+                dbname="symfony_project"
+                user="%database.user%"
+                password="%database.password%"
+            />
+        </doctrine:config>
+
+    .. code-block:: php
+
+        $container->loadFromExtension('doctrine', array(
+            'dbal' => array(
+                'driver'   => 'pdo_mysql',
+                'dbname'   => 'symfony_project',
+                'user'     => '%database.user%',
+                'password' => '%database.password%',
+            )
+        ));
+
+Then you can set the default value of the ``database.user`` and ``database.password``
+parameters by setting the ``SYMFONY__DATABASE__USER`` and
+``SYMFONY__DATABASE__PASSWORD`` environment variables respectively.
+
+If you're using Apache, those can be set using the following ``VirtualHost``
+configuration:
 
 .. code-block:: apache
 
@@ -55,23 +92,29 @@ the following ``VirtualHost`` configuration:
         $ export SYMFONY__DATABASE__USER=user
         $ export SYMFONY__DATABASE__PASSWORD=secret
 
-Now that you have declared an environment variable, it will be present
-in the PHP ``$_SERVER`` global variable. Symfony then automatically sets all
-``$_SERVER`` variables prefixed with ``SYMFONY__`` as parameters in the service
-container.
+``SYMFONY__`` prefixed environment variables are ignored when their corresponding
+parameters are set in your configuration files. Note also that their values are
+inlined into dumped service containers so that changing them at runtime won't
+affect your service container unless you recompile it afterwards.
+
+Reference Environment Variables at Run-time
+-------------------------------------------
 
-You can now reference these parameters wherever you need them.
+You can reference any environment variables in your service container by using
+special parameters named after the variables you want to use encapsed between
+``env(...)``.
+
+For example, if you want to use the value of the ``DATABASE_HOST`` environment
+variable into you service container configuration, you can reference it using
+``%env(DATABASE_HOST)%``:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         doctrine:
             dbal:
-                driver:   pdo_mysql
-                dbname:   symfony_project
-                user:     '%database.user%'
-                password: '%database.password%'
+                host: '%env(DATABASE_HOST)%'
 
     .. code-block:: xml
 
@@ -80,24 +123,51 @@ You can now reference these parameters wherever you need them.
 
         <doctrine:config>
             <doctrine:dbal
-                driver="pdo_mysql"
-                dbname="symfony_project"
-                user="%database.user%"
-                password="%database.password%"
+                host="%env(DATABASE_HOST)%"
             />
         </doctrine:config>
 
     .. code-block:: php
 
         $container->loadFromExtension('doctrine', array(
             'dbal' => array(
-                'driver'   => 'pdo_mysql',
-                'dbname'   => 'symfony_project',
-                'user'     => '%database.user%',
-                'password' => '%database.password%',
+                'host' => '%env(DATABASE_HOST)%',
             )
         ));
 
+``env(...)`` parameters can have default values be set and used whenever their
+corresponding environment variables are not found:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        parameters:
+            env(DATABASE_HOST): localhost
+
+    .. code-block:: 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 http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <parameters>
+                <parameter key="env(DATABASE_HOST)">localhost</parameter>
+            </parameters>
+         </container>
+
+    .. code-block:: php
+
+        $container->setParameter('env(DATABASE_HOST)', 'localhost');
+
+Unlike ``SYMFONY__`` prefixed environment variables, ``env(...)`` parameters are
+turned into run-time environment variable reads, so that dumped containers can
+be reconfigured dynamically even after being compiled.
+
+.. versionadded:: 3.2
+    ``env(...)`` parameters were introduced in Symfony 3.2.
+
 Constants
 ---------