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

Author: nicolas-grekas

configuration/external_parameters.rst

@@ -13,65 +13,25 @@ you to easily do this.
 Environment Variables
 ---------------------
 
-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:
+.. versionadded:: 3.2
+    ``env(...)`` parameters were introduced in Symfony 3.2.
 
-* ``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.
+You can reference environment variables by using special parameters named after
+the variables you want to use encapsed between ``env(...)``. Their actual values
+will be resolved at runtime, so that dumped containers can be reconfigured
+dynamically even after being compiled.
 
-For example, if you're using Apache, environment variables can be set using
-the following ``VirtualHost`` configuration:
-
-.. code-block:: apache
-
-    <VirtualHost *:80>
-        ServerName      Symfony
-        DocumentRoot    "/path/to/symfony_2_app/web"
-        DirectoryIndex  index.php index.html
-        SetEnv          SYMFONY__DATABASE__USER user
-        SetEnv          SYMFONY__DATABASE__PASSWORD secret
-
-        <Directory "/path/to/symfony_2_app/web">
-            AllowOverride All
-            Allow from All
-        </Directory>
-    </VirtualHost>
-
-.. note::
-
-    The example above is for an Apache configuration, using the `SetEnv`_
-    directive. However, this will work for any web server which supports
-    the setting of environment variables.
-
-    Also, in order for your console to work (which does not use Apache),
-    you must export these as shell variables. On a Unix system, you can run
-    the following:
-
-    .. code-block:: bash
-
-        $ 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.
-
-You can now reference these parameters wherever you need them.
+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)%`` in your configuration files:
 
 .. 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 +40,84 @@ 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');
+
+If you're using Apache, environment variables can be set e.g. using the following
+``VirtualHost`` configuration:
+
+.. code-block:: apache
+
+    <VirtualHost *:80>
+        ServerName      Symfony
+        DocumentRoot    "/path/to/symfony_2_app/web"
+        DirectoryIndex  index.php index.html
+        SetEnv          DATABASE_USER user
+        SetEnv          DATABASE_PASSWORD secret
+
+        <Directory "/path/to/symfony_2_app/web">
+            AllowOverride All
+            Allow from All
+        </Directory>
+    </VirtualHost>
+
+.. note::
+
+    All popular web servers support setting environment variables. Read their
+    documentation to know how.
+
+    Also, in order for your console to work, you must export these as shell
+    variables. On a Unix system, you can run the following:
+
+    .. code-block:: bash
+
+        $ export DATABASE_USER=user
+        $ export DATABASE_PASSWORD=secret
+
+.. note::
+
+    You can also define the default value of any existing parameters using
+    special environement variables named after their corresponding parameter
+    prefixed with ``SYMFONY__`` after replacing dots by double underscores
+    (e.g. ``SYMFONY__FOO__BAR`` to set the default value of the ``foo.bar``
+    parameter). These default values are resolved when compiling the service
+    container and won't change at runtime once dumped.
+
 Constants
 ---------