From bac4e4734770bce0d42329f43fa99ab3d3e6c7a0 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 31 Oct 2018 17:27:19 +0100 Subject: [PATCH 1/2] Documented the loadForEnv() method --- components/dotenv.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/components/dotenv.rst b/components/dotenv.rst index 77d8fa78462..63d062da37b 100644 --- a/components/dotenv.rst +++ b/components/dotenv.rst @@ -67,6 +67,29 @@ The ``load()`` method never overwrites existing environment variables. Use the .. versionadded:: 4.2 The ``Dotenv::overload()`` method was introduced in Symfony 4.2. +If you define different ``.env`` files per environment (local, production, test, +etc.) use the ``loadForEnv()`` method to load the right file according to the +following overriding mechanism:: + + // ... + $dotenv->loadForEnv('dev', __DIR__.'/.env'); + // Looks for env vars in these files (and in this order): + // .env.dev.local + // .env.local + // .env.dev + // .env + + // ... + $dotenv->loadForEnv('test', __DIR__.'/.env'); + // In the 'test' environment, the '.env.local' file is ignored. This example + // looks for env vars in these files (and in this order): + // .env.test.local + // .env.test + // .env + +.. versionadded:: 4.2 + The ``Dotenv::loadForEnv()`` method was introduced in Symfony 4.2. + You should never store a ``.env`` file in your code repository as it might contain sensitive information; create a ``.env.dist`` file with sensible defaults instead. From 4dac1e295ac740d1e20ceade06224eae34bd0715 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 5 Nov 2018 11:48:46 +0100 Subject: [PATCH 2/2] Improved the explanation --- components/dotenv.rst | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/components/dotenv.rst b/components/dotenv.rst index 63d062da37b..6a7262ad446 100644 --- a/components/dotenv.rst +++ b/components/dotenv.rst @@ -67,9 +67,15 @@ The ``load()`` method never overwrites existing environment variables. Use the .. versionadded:: 4.2 The ``Dotenv::overload()`` method was introduced in Symfony 4.2. -If you define different ``.env`` files per environment (local, production, test, -etc.) use the ``loadForEnv()`` method to load the right file according to the -following overriding mechanism:: +Symfony follows and promotes the `app config recommendations`_ made by the +Twelve-Factor App methodology. Among other things, it's recommended to not group +env vars into environments (``dev``, ``prod``, ``test``, etc.) + +When deploying apps you should follow that recommendation strictly. However, +when developing apps on your local machine, testing multiple apps in different +environments with regular env vars is cumbersome. That's why Symfony provides a +feature to define env vars per environment using the ``loadForEnv()`` method +(but you should only use it on your local machine, not in production servers):: // ... $dotenv->loadForEnv('dev', __DIR__.'/.env'); @@ -87,6 +93,13 @@ following overriding mechanism:: // .env.test // .env +The ``.env`` file should be committed to the shared repository and contains the +default env var values for the app. The optional ``.env.local`` file shouldn't +be committed to the repository and overrides the values of some env vars to run +the app on your local machine. The other two optional files (``.env`` + +"environment name" + ``.local`` and ``.env`` + "environment name") work +similarly, but they are specific to some environment. + .. versionadded:: 4.2 The ``Dotenv::loadForEnv()`` method was introduced in Symfony 4.2. @@ -135,3 +148,4 @@ Embed commands via ``$()`` (not supported on Windows): .. _Packagist: https://packagist.org/packages/symfony/dotenv .. _twelve-factor applications: http://www.12factor.net/ +.. _`app config recommendations`: https://12factor.net/config