@@ -62,9 +62,54 @@ 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::
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 whereas the files loaded later override the variables
79+ defined in previously loaded files:
80+
81+ #. If ``.env `` exists, it is loaded first. In case there's no ``.env `` file but a
82+ ``.env.dist ``, this one will be loaded instead.
83+ #. If one of the previously mentioned files contains the ``APP_ENV `` variable, the
84+ variable is populated and used to load environment-specific files hereafter. If
85+ ``APP_ENV `` is not defined in either of the previously mentioned files, ``dev `` is
86+ assumed for ``APP_ENV `` and populated by default.
87+ #. If there's a ``.env.local `` representing general local environment variables it's loaded now.
88+ #. If there's a ``.env.$env.local `` file, this one is loaded. Otherwise, it falls
89+ back to ``.env.$env ``.
90+
91+ This might look complicated at first glance but it gives you the opportunity to commit
92+ multiple environment-specific files that can then be adjusted to your local environment
93+ easily. Given you commit ``.env ``, ``.env.test `` and ``.env.dev `` to represent different
94+ configuration settings for your environments, each of them can be adjusted by using
95+ ``.env.local ``, ``.env.test.local `` and ``.env.dev.local `` respectively.
96+
97+ .. note ::
98+
99+ ``.env.local `` is always ignored in ``test `` environment because tests should produce the
100+ same results for everyone.
101+
102+ You can adjust the variable defining the environment, default environment and test
103+ environments by passing them as additional arguments to ``Dotenv::loadEnv() ``
104+ (see :method: `Symfony\\ Component\\ Dotenv\\ Dotenv::loadEnv ` for details).
105+
106+ .. versionadded :: 4.2
107+
108+ The ``Dotenv::loadEnv() `` method was introduced in Symfony 4.2.
109+
65110You 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.
111+ contain sensitive information; create a ``.env.dist `` file (or multiple
112+ environment-specific ones as shown above) with sensible defaults instead.
68113
69114.. note ::
70115
0 commit comments