Updated the main article about env vars

Author: javiereguiluz

_build/redirection_map

@@ -412,3 +412,4 @@
 /session/avoid_session_start /session
 /session/sessions_directory /session
 /frontend/encore/legacy-apps /frontend/encore/legacy-applications
+/configuration/external_parameters /configuration/environment_variables

best_practices/configuration.rst

@@ -16,9 +16,9 @@ application behavior.
 .. best-practice::
 
     Define the infrastructure-related configuration options as
-    :doc:`environment variables </configuration/external_parameters>`. During
-    development, use the ``.env`` and ``.env.local`` files at the root of your project
-    to set these.
+    :doc:`environment variables </configuration/environment_variables>`. During
+    development, use the ``.env`` and ``.env.local`` files at the root of your
+    project to set these.
 
 By default, Symfony adds these types of options to the ``.env`` file when
 installing new dependencies in the app:

configuration.rst

@@ -208,7 +208,7 @@ percent signs - e.g. ``%locale%``.
 .. seealso::
 
     You can also set parameters dynamically, like from environment variables.
-    See :doc:`/configuration/external_parameters`.
+    See :doc:`/configuration/environment_variables`.
 
 For more information about parameters - including how to reference them from inside
 a controller - see :ref:`service-container-parameters`.

configuration/external_parameters.rst renamed to configuration/environment_variables.rst

@@ -1,34 +1,33 @@
 .. index::
-    single: Environments; External parameters
+    single: Environment Variables; env vars
 
-How to Set external Parameters in the Service Container
-=======================================================
+How to Configure Symfony With Environment Variables
+===================================================
 
 In :doc:`/configuration`, you learned how to manage your application
-configuration. At times, it may benefit your application to store certain
-credentials outside of your project code. Database configuration is one such
-example. The flexibility of the Symfony service container allows you to do this.
+configuration. In this article you'll learn how to use environment variables (or
+"env vars" for short) to configure some of those options, which is a common
+practice to configure sensitive options such as credentials and passwords.
 
 .. _config-env-vars:
 
-Environment Variables
----------------------
+Referencing Env Vars in Configuration Files
+-------------------------------------------
 
-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.
-
-For example, when installing the ``doctrine`` recipe, database configuration is
-put in a ``DATABASE_URL`` environment variable:
+First, define the value of the env var, using your shell environment or the
+``.env`` file at the project root directory. For example, consider the
+``DATABASE_URL`` env var defined when installing the ``doctrine`` recipe (by
+convention the env var names are always uppercase):
 
 .. code-block:: bash
 
     # .env
     DATABASE_URL="mysql://db_user:[email protected]:3306/db_name"
 
-This variable is referenced in the service container configuration using
-``%env(DATABASE_URL)%``:
+Then, you can reference those env vars in any configuration option enclosing
+their names with ``env()``. Their actual values will be resolved at runtime
+(once per request), so that dumped containers can be reconfigured dynamically
+even after being compiled:
 
 .. configuration-block::
 
@@ -69,8 +68,8 @@ This variable is referenced in the service container configuration using
             ]
         ]);
 
-You can also give the ``env()`` parameters a default value: the default value
-will be used whenever the corresponding environment variable is *not* found:
+You can also give the ``env()`` parameters a default value, which will be used
+whenever the corresponding environment variable is *not* found:
 
 .. configuration-block::
 
@@ -101,7 +100,7 @@ will be used whenever the corresponding environment variable is *not* found:
 .. _configuration-env-var-in-prod:
 
 Configuring Environment Variables in Production
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------
 
 During development, you'll use the ``.env`` file to configure your environment
 variables. On your production server, it is recommended to configure these at

configuration/environments.rst

@@ -361,4 +361,4 @@ includes the following:
 Going further
 -------------
 
-Read the article on :doc:`/configuration/external_parameters`.
+Read the article on :doc:`/configuration/environment_variables`.

doctrine/pdo_session_storage.rst

@@ -68,8 +68,8 @@ To use it, first register a new handler service:
 
 .. tip::
 
-    Configure the database credentials as
-    :doc:`parameters defined with environment variables </configuration/external_parameters>`
+    Configure the database credentials
+    :doc:`using environment variables in the config file </configuration/environment_variables>`
     to make your application more secure.
 
 Next, tell Symfony to use your service as the session handler:

reference/configuration/swiftmailer.rst

@@ -253,11 +253,10 @@ the information will be available in the profiler.
 
 .. tip::
 
-    The following options can be set via environment variables using the
-    ``%env()%`` syntax: ``url``, ``transport``, ``username``, ``password``,
-    ``host``, ``port``, ``timeout``, ``source_ip``, ``local_domain``,
-    ``encryption``, ``auth_mode``.
-    For details, see the :doc:`/configuration/external_parameters` article.
+    The following options can be set via environment variables: ``url``,
+    ``transport``, ``username``, ``password``, ``host``, ``port``, ``timeout``,
+    ``source_ip``, ``local_domain``, ``encryption``, ``auth_mode``. For details,
+    see: :doc:`/configuration/environment_variables`.
 
 Using Multiple Mailers
 ----------------------

service_container/parameters.rst

@@ -245,7 +245,7 @@ for all parameters that are arrays.
 Environment Variables and Dynamic Values
 ----------------------------------------
 
-See :doc:`/configuration/external_parameters`.
+See :doc:`/configuration/environment_variables`.
 
 .. _component-di-parameters-constants: