8000 Documented the loadForEnv() method by javiereguiluz · Pull Request #10626 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

Documented the loadForEnv() method #10626

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Documented the loadForEnv() method #10626

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bac4e47
Documented the loadForEnv() method
javiereguiluz Oct 31, 2018
4dac1e2
Improved the explanation
javiereguiluz Nov 5, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Improved the explanation
  • Loading branch information
@javiereguiluz
javiereguiluz committed Nov 5, 2018
commit 4dac1e295ac740d1e20ceade06224eae34bd0715
20 changes: 17 additions & 3 deletions components/dotenv.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand All @@ -87,6 +93,13 @@ following overriding mechanism::
// .env.test
// .env

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Similarly to ``DotEnv::load()``, ``DotEnv::loadForEnv()`` never overwrites existing environment variables, nor variables defined by files loaded previously. For instance, if the same variable is defined in both `.env` and `.env.test.local`, the value will be the one defined in `.env.test.local`, because this file is loaded first by ``DotEnv::loadForEnv()``.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add somewhere something similar to https://github.com/bkeepers/dotenv/blob/master/README.md#can-i-use-dotenv-in-production last paragraph:

please note that env vars that are general to all environments should be stored in .env. Then, environment specific env vars should be stored in .env.<that environment's name>.

i.e no need to repeat all env vars. Only the ones likely to be specific for the target 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
Copy link
Member
@dunglas dunglas Nov 5, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
default env var values for the app. The optional ``.env.local`` file shouldn't
default env var values for the app. The ``.env`` file should contain development-only settings. It **must not** contain any settings used in production. They are placeholder values helping during the onboarding process. 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.

Copy link
Member
@dunglas dunglas Nov 5, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May I suggest to add the following:

Suggested change
``DotEnv::loadForEnv()`` implements the exact same behavior than Ruby's `dotenv library`_ and `Create React App's .env support`_. These projects provide extensive documentation about environment variables handling, that is worth reading.

.. versionadded:: 4.2
The ``Dotenv::loadForEnv()`` method was introduced in Symfony 4.2.

Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
.. _`app config recommendations`: https://12factor.net/config
.. _`app config recommendations`: https://12factor.net/config
.. _`dotenv library`: https://github.com/bkeepers/dotenv
.. _`Create React App's .env support`: 4ECF https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#what-other-env-files-can-be-used

0