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 all commits
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
37 changes: 37 additions & 0 deletions components/dotenv.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,42 @@ The ``load()`` method never overwrites existing environment variables. Use the
.. versionadded:: 4.2
The ``Dotenv::overload()`` method was introduced in Symfony 4.2.

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');
// Looks for env vars in these files (and in this order):
// .env.dev.local
// .env.local
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.

Will be loaded after .env.dev

Copy link
Contributor

Choose a reason for hiding this comment

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

Will be loaded after .env.dev

Hmm. Are you sure? I didn't check the code, but if it's true it's not respecting the same priorities as https://github.com/bkeepers/dotenv/blob/master/README.md#what-other-env-files-can-i-use, i.e:

  • .env.[env].local
  • .env.local
  • .env.[env]
  • .env

Also, what about using the same presentation as bkeepers/dotenv? (The table with complementary information)

Copy link
Contributor

@ogizanagi ogizanagi 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.

But https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#what-other-env-files-can-be-used does load .env.local after .env.[env]...

IMHO, loading .env.local before .env.[env] makes more sense, as x.local should always allow override. Either you use .env.local to override for all environments, either you use .env.[env].local for a specific env. But .env and .env.[env] will only contains sensible defaults, so .env.[env] should not have precedence over .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

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.

You should never store a ``.env`` file in your code repository as it might
Copy link
Member

Choose a reason for hiding this comment

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

This sentence should be remove in favor of the paragraph you introduced, right?

contain sensitive information; create a ``.env.dist`` file with sensible
defaults instead.
Expand Down Expand Up @@ -112,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`: https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#what-other-env-files-can-be-used