symfony · weaverryan · Nov 16, 2018 · Nov 15, 2018
diff --git a/best_practices/configuration.rst b/best_practices/configuration.rst
@@ -19,7 +19,8 @@ application behavior.
 
     Define the infrastructure-related configuration options as
     :doc:`environment variables </configuration/external_parameters>`. During
-    development, use the ``.env`` file at the root of your project to set these.
+    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:
@@ -42,6 +43,9 @@ they have nothing to do with the application's behavior. In other words, your
 application doesn't care about the location of your database or the credentials
 to access to it, as long as the database is correctly configured.
 
+To override these variables with machine-specific or sensitive values, create a
+``env.local`` file. This file should not be added to version control.
+
 .. caution::
 
     Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables
@@ -56,14 +60,18 @@ Canonical Parameters
 
 .. best-practice::
 
-    Define all your application's env vars in the ``.env.dist`` file.
+    Define all your application's env vars in the ``.env`` file.
+
+Symfony includes a configuration file called ``.env`` at the project root, which
+stores the canonical list of environment variables for the application. This
+file should be stored in version control and so should only contain non-sensitive
+default values.
 
-Symfony includes a configuration file called ``.env.dist`` at the project root,
-which stores the canonical list of environment variables for the application.
+.. caution::
 
-Whenever a new env var is defined for the application, you should also add it to
-this file and submit the changes to your version control system so your
-workmates can update their ``.env`` files.
+    Applications created before November 2018 had a slightly different system,
+    involving a ``.env.dist`` file. For information about upgrading, see:
+    :doc:`/configuration/dot-env-changes`.
 
 Application-Related Configuration
 ---------------------------------

diff --git a/configuration.rst b/configuration.rst
@@ -263,10 +263,12 @@ a controller - see :ref:`service-container-parameters`.
 The .env File & Environment Variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There is also a ``.env`` file which is loaded. Its contents become environment
-variables in the dev environment, making it easier to reference environment
-variables in your code. When you install packages, more environment variables are
-added to this file. But you can also add your own variables.
+There is also a ``.env`` file which is loaded and its contents become environment
+variables. This is useful during development, or if setting environment variables
+is difficult for your deployment.
+
+When you install packages, more environment variables are added to this file. But
+you can also add your own.
 
 Environment variables can be referenced in any other configuration files by using
 a special syntax. For example, if you install the ``doctrine`` package, then you
@@ -285,18 +287,34 @@ This is referenced inside ``config/packages/doctrine.yaml``:
 
 For more details about environment variables, see :ref:`config-env-vars`.
 
+.. caution::
+
+    Applications created before November 2018 had a slightly different system,
+    involving a ``.env.dist`` file. For information about upgrading, see:
+    :doc:`configuration/dot-env-changes`.
+
 The ``.env`` file is special, because it defines the values that usually change
 on each server. For example, the database credentials on your local development
-machine might be different from your workmates. That's why this file is **not
-committed to the shared repository** and is only stored on your machine. In
-fact, the ``.gitignore`` file that comes with Symfony prevents it from being
-committed.
-
-However, a ``.env.dist`` file *is* committed (with dummy values). This file
-isn't read by Symfony: it's just a reference so that Symfony knows which
-variables need to be defined in the ``.env`` file. If you add or remove keys to
-``.env``, add or remove them from ``.env.dist`` too, so both files are always
-in sync.
+machine might be different from your workmates. The ``.env`` file should contain
+sensible, non-secret *default* values for all of your environment variables and
+*should* be commited to your repository.
+
+To override these variables with machine-specific or sensitive values, create a
+``env.local`` file. This file is **not committed to the shared repository** and
+is only stored on your machine. In fact, the ``.gitignore`` file that comes with
+Symfony prevents it from being committed.
+
+You can also create a few other ``.env`` files that will be loaded:
+
+* ``.env.{environment}``: e.g. ``.env.test`` will be loaded in the ``test`` environment
+  and committed to your repository.
+
+* ``.env.{environment}.local``: e.g. ``.env.prod.local`` will be loaded in the
+  ``prod`` environment but will *not* be committed to your repository.
+
+If you decide to set real environment variables on production, the ``.env`` files
+will *not* be loaded if Symfony detects that a real ``APP_ENV`` environment variable
+exists and is set to ``prod``.
 
 Environments & the Other Config Files
 -------------------------------------

diff --git a/configuration/dot-env-changes.rst b/configuration/dot-env-changes.rst
@@ -0,0 +1,91 @@
+Nov 2018 Changes to .env & How to Update
+========================================
+
+In November 2018, several changes were made to the core Symfony *recipes* related
+to the ``.env`` file. These changes make working with environment variables easier
+and more consistent - especially when writing functional tests.
+
+If your app was started before November 2018, your app **does not require any changes
+to keep working**. However, if/when you are ready to take advantage of these improvements,
+you will need to make a few small updates.
+
+What Changed Exactly?
+---------------------
+
+But first, what changed? On a high-level, not much. Here's a summary of the most
+important changes:
+
+* A) The ``.env.dist`` file no longer exists. Its contents should be moved to your
+  ``.env`` file (see the next point).
+
+* B) The ``.env`` file **is** now commited to your repository. It was previously ignored
+  via the ``.gitignore`` file (the updated recipe does not ignore this file). Because
+  this file is committed, it should contain non-sensitive, default values. Basically,
+  the ``.env.dist`` file was moved to ``.env``.
+
+* C) A ``.env.local`` file can now be created to *override* environment variables for
+  your machine. This file is ignored in the new ``.gitignore``.
+
+* D) When testing, your ``.env`` file is now read, making it consistent with all
+  other environments. You can also create a ``.env.test`` file for test-environment
+  overrides.
+
+There are a few other improvements, but these are the most important. To take advantage
+of these, you *will* need to modify a few files in your existing app.
+
+Updating My Application
+-----------------------
+
+If you created your application after November 15th 2018, you don't need to make
+any changes! Otherwise, here is the list of changes you'll need to make - these
+changes can be made to any Symfony 3.4 or higher app:
+
+#. Create a new `src/.bootstrap.php`_ file in your project. This file loads Composer's
+   autoloader and loads all the ``.env`` files as needed.
+
+#. Update your `public/index.php`_ (`index.php diff`_) file to load the new ``src/.bootstrap.php``
+   file. If you've customized this file, make sure to keep those changes (but use
+   the rest of the changes).
+
+#. Update your `bin/console`_ (`bin/console diff`_) file to load the new ``src/.bootstrap.php`` file.
+
+#. Update ``.gitignore``:
+
+    .. code-block:: diff
+
+        # .gitignore
+        # ...
+
+        ###> symfony/framework-bundle ###
+        - /.env
+        + /.env.local
+        + /.env.*.local
+
+        # ...
+
+#. Rename ``.env`` to ``.env.local`` and ``.env.dist`` to ``.env``:
+
+    .. code-block:: terminal
+
+        # Unix
+        $ mv .env .env.local
+        $ git mv .env.dist .env
+
+        # Windows
+        $ mv .env .env.local
+        $ git mv .env.dist .env
+
+    You can also update the `comment on the top of .env`_ to reflect the new changes.
+
+#. If you're using PHPUnit, you will also need to `create a new .env.test`_ file
+   and update your `phpunit.xml.dist file`_ so it loads the ``src/.bootstrap.php``
+   file.
+
+.. _`src/.bootstrap.php`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/src/.bootstrap.php
+.. _`public/index.php`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/public/index.php
+.. _`index.php diff`: https://github.com/symfony/recipes/compare/8a4e5555e30d5dff64275e2788a901f31a214e79...86e2b6795c455f026e5ab0cba2aff2c7a18511f7#diff-473fca613b5bda15d87731036cb31586
+.. _`bin/console`: https://github.com/symfony/recipes/blob/master/symfony/console/3.3/bin/console
+.. _`bin/console diff`: https://github.com/symfony/recipes/compare/8a4e5555e30d5dff64275e2788a901f31a214e79...86e2b6795c455f026e5ab0cba2aff2c7a18511f7#diff-2af50efd729ff8e61dcbd936cf2b114b
+.. _`comment on the top of .env`: https://github.com/symfony/recipes/blob/master/symfony/flex/1.0/.env
+.. _`create a new .env.test`: https://github.com/symfony/recipes/blob/master/symfony/phpunit-bridge/3.3/.env.test
+.. _`phpunit.xml.dist file`: https://github.com/symfony/recipes/blob/master/symfony/phpunit-bridge/3.3/phpunit.xml.dist
diff --git a/configuration/environments.rst b/configuration/environments.rst
@@ -80,11 +80,11 @@ Executing an Application in different Environments
 --------------------------------------------------
 
 To execute the application in each environment, change the ``APP_ENV``
-environment variable. During development, this is done in ``.env``:
+environment variable. During development, this is done in ``.env`` or in ``.env.local``:
 
 .. code-block:: bash
 
-    # .env
+    # .env or .env.local
     APP_ENV=dev
 
     # or for test:
@@ -95,7 +95,7 @@ your application in the configured environment.
 
 .. tip::
 
-    In production, it is recommended to configure the environment variables in
+    In production, you can use real environment variables via
     your :ref:`web server configuration <configuration-env-var-in-prod>`.
 
 .. note::
@@ -109,14 +109,10 @@ the environment variable is passed to the kernel::
     // public/index.php
 
     // ...
-    $kernel = new Kernel($_SERVER['APP_ENV'] ?? 'dev', $_SERVER['APP_DEBUG'] ?? false);
+    $kernel = new Kernel($_SERVER['APP_ENV'], $_SERVER['APP_DEBUG']);
 
     // ...
 
-You can also replace ``$_SERVER['APP_ENV'] ?? 'dev'`` by just ``'dev'`` to
-always run the application in the dev environment, independent of the
-``APP_ENV`` variable.
-
 .. note::
 
     The ``test`` environment is used when writing functional tests and is
@@ -251,7 +247,7 @@ environment through your browser:
 
 .. code-block:: bash
 
-    # .env
+    # .env or .env.local
     APP_ENV=benchmark
 
 .. sidebar:: Importing configuration

diff --git a/deployment.rst b/deployment.rst
@@ -125,21 +125,21 @@ B) Configure your Environment Variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Most Symfony applications read their configuration from environment variables.
-While developing locally, you'll usually store these in a ``.env`` file. On production,
-you have two options:
+While developing locally, you'll usually store these in ``.env`` and ``.env.local``
+(for local overrides). On production, you have two options:
 
 1. Create "real" environment variables. How you set environment variables, depends
    on your setup: they can be set at the command line, in your Nginx configuration,
    or via other methods provided by your hosting service.
 
-2. Or, create a ``.env`` file just like your local development (see note below)
+2. Or, create a ``.env.local`` file just like your local development (see note below)
 
 There is no significant advantage to either of the two options: use whatever is
 most natural in your hosting environment.
 
 .. note::
 
-    If you use the ``.env`` file on production, you may need to move your
+    If you use the ``.env.*`` files on production, you may need to move your
     ``symfony/dotenv`` dependency from ``require-dev`` to ``require`` in ``composer.json``:
 
     .. code-block:: terminal

diff --git a/doctrine.rst b/doctrine.rst
@@ -39,7 +39,7 @@ The database connection information is stored as an environment variable called
 
 .. code-block:: text
 
-    # .env
+    # .env (or override DATABASE_URL in .env.local to avoid committing your changes)
 
     # customize this line!
     DATABASE_URL="mysql://db_user:[email protected]:3306/db_name"

diff --git a/doctrine/dbal.rst b/doctrine/dbal.rst
@@ -31,7 +31,7 @@ Then configure the ``DATABASE_URL`` environment variable in ``.env``:
 
 .. code-block:: text
 
-    # .env
+    # .env (or override DATABASE_URL in .env.local to avoid committing your changes)
 
     # customize this line!
     DATABASE_URL="mysql://db_user:[email protected]:3306/db_name"

diff --git a/doctrine/reverse_engineering.rst b/doctrine/reverse_engineering.rst
@@ -47,7 +47,7 @@ to a post record thanks to a foreign key constraint.
     ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;
 
 Before diving into the recipe, be sure your database connection parameters are
-correctly setup in the ``.env`` file.
+correctly setup in the ``.env`` file (or ``.env.local`` override file).
 
 The first step towards building entity classes from an existing database
 is to ask Doctrine to introspect the database and generate the corresponding

diff --git a/email.rst b/email.rst
@@ -34,6 +34,8 @@ environment variable in the ``.env`` file:
 
 .. code-block:: bash
 
+    # .env (or override MAILER_URL in .env.local to avoid committing your changes)
+
     # use this to disable email delivery
     MAILER_URL=null://localhost
 

diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst
@@ -29,7 +29,6 @@ Symfony application:
 
     quick_tour/
     ├─ .env
-    ├─ .env.dist
     ├─ bin/console
     ├─ composer.json
     ├─ composer.lock

diff --git a/security/force_https.rst b/security/force_https.rst
@@ -80,7 +80,7 @@ access control:
 
 To make life easier while developing, you can also use an environment variable,
 like ``requires_channel: '%env(SECURE_SCHEME)%'``. In your ``.env`` file, set
-``SECURE_SCHEME`` to ``http`` locally, but ``https`` on production.
+``SECURE_SCHEME`` to ``http`` by default, but override it to ``https`` on production.
 
 See :doc:`/security/access_control` for more details about ``access_control``
 in general.

diff --git a/testing.rst b/testing.rst
@@ -179,18 +179,7 @@ As an example, a test could look like this::
     To run your functional tests, the ``WebTestCase`` class needs to know which
     is the application kernel to bootstrap it. The kernel class is usually
     defined in the ``KERNEL_CLASS`` environment variable (included in the
-    default ``phpunit.xml.dist`` file provided by Symfony):
-
-    .. code-block:: xml
-
-        <?xml version="1.0" charset="utf-8" ?>
-        <phpunit>
-            <php>
-                <!-- the value is the FQCN of the application kernel -->
-                <env name="KERNEL_CLASS" value="App\Kernel" />
-            </php>
-            <!-- ... -->
-        </phpunit>
+    default ``.env.test`` file provided by Symfony):
 
     If your use case is more complex, you can also override the
     ``createKernel()`` or ``getKernelClass()`` methods of your functional test,
@@ -939,6 +928,33 @@ method::
         'debug'       => false,
     ));
 
+Customizing Database URL / Environment Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you need to customize some environment variables for your tests (e.g. the
+``DATABASE_URL`` used by Doctrine), you can do that by overriding anything you
+need in your ``.env.test`` file:
+
+.. code-block:: text
+
+    # .env.test
+    DATABASE_URL="mysql://db_user:[email protected]:3306/db_name_test"
+
+    # use SQLITE
+    # DATABASE_URL="sqlite:///%kernel.project_dir%/var/app.db"
+
+This file is automatically read in the ``test`` environment: any keys here override
+the defaults in ``.env``.
+
+.. caution::
+
+    Applications created before November 2018 had a slightly different system,
+    involving a ``.env.dist`` file. For information about upgrading, see:
+    :doc:`configuration/dot-env-changes`.
+
+Sending Custom Headers
+~~~~~~~~~~~~~~~~~~~~~~
+
 If your application behaves according to some HTTP headers, pass them as the
 second argument of ``createClient()``::