@@ -62,9 +62,52 @@ The ``load()`` method never overwrites existing environment variables. Use the
6262 // ...
6363 $dotenv->overload(__DIR__.'/.env');
6464
65+ As you're working with the ``Dotenv `` component you'll notice that you might want
66+ to have different files depending on the environment you're working in. Typically
67+ this happens for local development or Continuous Integration where you might
68+ want to have different files for your ``test `` and ``dev `` environments.
69+
70+ You can use ``Dotenv::loadEnv() `` to ease this process for you::
71+
72+ use Symfony\Component\Dotenv\Dotenv;
73+
74+ $dotenv = new Dotenv();
75+ $dotenv->loadEnv(__DIR__.'/.env');
76+
77+ The ``Dotenv `` component will then look for the correct ``.env `` file to load
78+ in the following order::
79+
80+ 1. If ``.env `` exists, it is loaded first. In case there's no ``.env `` file but a
81+ ``.env.dist ``, this one will be loaded instead.
82+ 2. If one of the previously mentioned files contains the variable ``APP_ENV ``, the
83+ variable is populated and used to load environment specific files hereafter. If
84+ ``APP_ENV `` is not defined in either of the previously mentioned files, ``dev `` is
85+ assumed for ``APP_ENV `` and populated by default.
86+ 3. If there's an ``.env.$env.local `` file, this one is loaded. Otherwise, it falls
87+ back to ``.env.$env ``.
88+ 4. If there's an ``env.local `` it's loaded last.
89+
90+ This might look complicated at first glance but it gives you the opportunity to commit
91+ multiple environment specific files that can then be adjusted to your local environment
92+ easily. Given you commit ``.env ``, ``.env.test `` and ``.env.test `` to represent different
93+ configuration settings for your environments, each of them can be adjusted by using
94+ ``.env.local ``, ``.env.test.local `` and ``.env.test.local `` respectively.
95+
96+ .. note ::
97+
98+ ``.env.local `` is always ignored in ``test `` env because tests should produce the
99+ same results for everyone.
100+
101+ You can adjust the variable defining the environment, default environment and test
102+ environments by passing then as additional arguments to ``Dotenv::loadEnv() ``
103+ (see :method: `Symfony\C omponent\D otenv::loadEnv ` for details).
104+
105+ .. versionadded :: 4.2
106+ The ``Dotenv::loadEnv() `` method was introduced in Symfony 4.2.
107+
65108You should never store a ``.env `` file in your code repository as it might
66- contain sensitive information; create a ``.env.dist `` file with sensible
67- defaults instead.
109+ contain sensitive information; create a ``.env.dist `` (or multiple environment
110+ specific ones as shown above)) file with sensible defaults instead.
68111
69112.. note ::
70113
0 commit comments