[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 their values at runtime
+won't affect these containers unless you recompile them afterwards.
 
-You can now reference these parameters wherever you need them.
+Reference Environment Variables at Run-time
+-------------------------------------------
+
+You can reference any environment variables for it to be used in your service
+container by using special parameters named after the variables you want to use
+encapsed in 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 the
+`%env(DATABASE_HOST)%` parameter:
 
 .. 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,48 @@ 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 that are going to be 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
+truned into run-time environment variable reads, so that a dumped container can
+be reconfigured dynamically even after being compiled and dumped.
+
 Constants
 ---------