diff --git a/configuration/external_parameters.rst b/configuration/external_parameters.rst
index 57f428ace3c..deb2a649ace 100644
--- a/configuration/external_parameters.rst
+++ b/configuration/external_parameters.rst
@@ -13,119 +13,114 @@ 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:
-
-* ``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're using Apache, environment variables can be set using the
-`SetEnv`_ directive with the following ``VirtualHost`` configuration:
-
-.. code-block:: apache
-
-
- ServerName Symfony
- DocumentRoot "/path/to/symfony_2_app/web"
- DirectoryIndex index.php index.html
- SetEnv SYMFONY__DATABASE__USER user
- SetEnv SYMFONY__DATABASE__PASSWORD secret
-
-
- AllowOverride All
- Allow from All
-
-
-
-For Nginx web servers, the environment variables can be set with the `fastcgi_param`_
-directive. For example, in the configuration file where the ``fastcgi_params``
-file is included:
-
-.. code-block:: nginx
-
- server {
- server_name domain.tld www.domain.tld;
- root /var/www/project/web;
-
- location / {
- try_files $uri /app.php$is_args$args;
- }
-
- location ~ ^/app\.php(/|$) {
- fastcgi_pass unix:/var/run/php5-fpm.sock;
- fastcgi_split_path_info ^(.+\.php)(/.*)$;
- include fastcgi_params;
- fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
- fastcgi_param DOCUMENT_ROOT $realpath_root;
- fastcgi_param SYMFONY__DATABASE__USER user;
- fastcgi_param SYMFONY__DATABASE__PASSWORD secret;
- internal;
- }
-
- # ...
- }
+.. versionadded:: 3.2
+ ``env()`` parameters were introduced in Symfony 3.2.
-.. note::
-
- The examples above are for an Apache and Nginx configuration. 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 a web server),
- you must export these as shell variables. On a Unix system, you can run
- the following:
-
- .. code-block:: terminal
+You can reference environment variables by using special parameters named after
+the variables you want to use enclosed between ``env()``. Their actual values
+will be resolved at runtime (once per request), so that dumped containers can be
+reconfigured dynamically even after being compiled.
- $ 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 in you service container configuration, you can reference it using
+``%env(DATABASE_HOST)%`` in your configuration files:
.. configuration-block::
.. code-block:: yaml
+ # app/config/config.yml
doctrine:
dbal:
- driver: pdo_mysql
- dbname: symfony_project
- user: '%database.user%'
- password: '%database.password%'
+ host: '%env(DATABASE_HOST)%'
.. code-block:: xml
+
.. code-block:: php
+ // app/config/config.php
$container->loadFromExtension('doctrine', array(
'dbal' => array(
- 'driver' => 'pdo_mysql',
- 'dbname' => 'symfony_project',
- 'user' => '%database.user%',
- 'password' => '%database.password%',
+ 'host' => '%env(DATABASE_HOST)%',
)
));
+You can also give the ``env()`` parameters a default value: the default value
+will be used whenever the corresponding environment variable is *not* found:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/parameters.yml
+ parameters:
+ database_host: '%env(DATABASE_HOST)%'
+ env(DATABASE_HOST): localhost
+
+ .. code-block:: xml
+
+
+
+
+
+
+ %env(DATABASE_HOST)%
+ localhost
+
+
+
+ .. code-block:: php
+
+ // app/config/parameters.php
+ $container->setParameter('database_host', '%env(DATABASE_HOST)%');
+ $container->setParameter('env(DATABASE_HOST)', 'localhost');
+
+Setting environment variables is generally done at the web server level or in the
+terminal. If you're using Apache, Nginx or just the console, you can use e.g. one
+of the following:
+
+.. configuration-block::
+
+ .. code-block:: apache
+
+
+ # ...
+
+ SetEnv DATABASE_USER user
+ SetEnv DATABASE_PASSWORD secret
+
+
+ .. code-block:: nginx
+
+ fastcgi_param DATABASE_USER user
+ fastcgi_param DATABASE_PASSWORD secret
+
+ .. code-block:: terminal
+
+ $ export DATABASE_USER=user
+ $ export DATABASE_PASSWORD=secret
+
+.. tip::
+
+ You can also define the default value of any existing parameters using
+ special environment variables named after their corresponding parameter
+ prefixed with ``SYMFONY__`` after replacing dots by double underscores
+ (e.g. ``SYMFONY__KERNEL__CHARSET`` to set the default value of the
+ ``kernel.charset`` parameter). These default values are resolved when
+ compiling the service container and won't change at runtime once dumped.
+
Constants
---------