Add docs for the Dotenv component #7350

fabpot · 2017-01-11T02:10:17Z

yceruto · 2017-01-11T03:04:54Z

components/env.rst

+
+.. code-block:: php
+
+    $dbUser = getenv('DB_USER);


Missing single quote 'DB_USER'

w3guy · 2017-01-11T05:31:14Z

components/env.rst

+
+    Symfony Env never overwrites existing environment variables.
+
+You should never store a ``.env`` file is your code repository as it might


Typo. Should be "in your code"

javiereguiluz

Thanks for providing the docs for this component. Everything is well explained and easy to understand, but I miss two things ... not for this component itself, but for when using it inside Symfony:

It's not clear enough for me how and when to use this. You mention that this is not for production. So should I create this only for dev? But then, why define it in dev if I already have app/config/config_dev.yml which works nicely without env vars? In other words, I don't know why I should "complicate" things in dev with env vars ... which probably are only needed in prod.
Is there a seamless integration with Symfony? If I define a .env file, could I use those vars with %env()% in my files automatically or should I do something?

javiereguiluz · 2017-01-11T07:35:46Z

components/env.rst

+environment variables (as recommended for `twelve-factor applications
+<http://www.12factor.net/>`_. Using an `.env` file to store those environment
+variables eases development and CI management by keeping them in one "standard"
+place and agnostic of the technology stack you are using (Nginx vs PHP build-in


build-in -> built-in ?

javiereguiluz · 2017-01-11T07:36:01Z

components/env.rst

+
+.. note::
+
+    PHP has a lot of different implementation of this "pattern". This


implementation -> implementations

javiereguiluz · 2017-01-11T07:37:28Z

components/env.rst

+
+Load an ``.env`` file in your PHP application via ``Dotenv::load()``:
+
+.. code-block:: php


In docs we are not allowed to use this php code block and we must the :: trick.

javiereguiluz · 2017-01-11T07:38:38Z

components/env.rst

+    Symfony Env never overwrites existing environment variables.
+
+You should never store a ``.env`` file is your code repository as it might
+contains sensitive information; creates a ``.env.dist`` file with sensible


creates -> create

javiereguiluz · 2017-01-11T07:40:59Z

components/env.rst

+contains sensitive information; creates a ``.env.dist`` file with sensible
+defaults instead.
+
+Symfony Env should only be used in development/testing/staging environments.


This recommendation contradicts a bit the previous one. If this file should only be used for non-production environments, then there's no problem storing this file in the repo because the credentials will be different. If this is true, then we don't need .env.dist and we can simplify things a lot.

@javiereguiluz db connection settings might still be sensitive information for testing/staging environments.

.env contains data that should be different for each dev, so having it in Git would not make sense.

jakzal · 2017-01-11T15:28:54Z

components/env.rst

+.. note::
+
+    PHP has a lot of different implementation of this "pattern". This
+    implementation goal is to replicate what ``source .env`` would do. So, it


This implementation's goal

jakzal · 2017-01-11T15:29:12Z

components/env.rst

+
+    PHP has a lot of different implementation of this "pattern". This
+    implementation goal is to replicate what ``source .env`` would do. So, it
+    tries to be as similar as possible with the default shells behavior, and


shell's behavior

although plural is probably correct in this case too.

jakzal · 2017-01-11T15:30:40Z

components/env.rst

+    Symfony Env never overwrites existing environment variables.
+
+You should never store a ``.env`` file is your code repository as it might
+contains sensitive information; creates a ``.env.dist`` file with sensible


it might contain

fabpot · 2017-01-11T18:48:40Z

@javiereguiluz Using a .env file to define env vars in projects is a "standard" used by many frameworks. You don't need to use it of course as we have other mechanisms in Symfony, but this component allows Symfony projects to be more similar with projects written with other frameworks and languages.

Regarding the integration with Symfony, it's going to be part of the whole new "bootstrap" experience I'm working on. More on that later.

xabbuh · 2017-01-12T06:42:16Z

components/env.rst

+
+You can install the component in 2 different ways:
+
+* :doc:`Install it via Composer </components/using_components>` (``symfony/env`` on `Packagist`_);


missing .. _Packagist: https://packagist.org/packages/symfony/env at the end of this document

xabbuh · 2017-01-12T06:43:28Z

components/env.rst

+=================
+
+    The Env Component parses ``.env`` files to make environment variables
+    stored in them accessible via ``getenv()``, ``$_ENV``, or ``$_SERVER``.


the Oxford comma should be removed

arf, I really don't like this but ok, done.

xabbuh · 2017-01-12T06:44:17Z

components/env.rst

+
+Sensitive information and environment-dependent settings should be defined as
+environment variables (as recommended for `twelve-factor applications
+<http://www.12factor.net/>`_. Using an `.env` file to store those environment


We do not inline the referenced URLs, but add them add the end of the document.

double backticks needed to enclose the filename

xabbuh · 2017-01-12T06:47:34Z

components/env.rst

+
+Given the following ``.env`` file content:
+
+.. code-block:: bash


~~Don't we have a better code block type we could use here?~~

xabbuh · 2017-01-12T06:49:29Z

components/env.rst

+Given the following ``.env`` file content:
+
+.. code-block:: bash
+


we should add a file comment too:

# .env DB_USER=root DB_PASS=pass

fabpot · 2017-01-12T15:12:43Z

Comments addressed

xabbuh · 2017-01-12T17:28:32Z

👍

Status: Reviewed

HeahDude · 2017-01-12T17:50:02Z

components/dotenv.rst

+
+First, require Symfony Dotenv via Composer:
+
+.. code-block:: bash


Don't we use terminal now?

HeahDude · 2017-01-12T17:56:34Z

components/dotenv.rst

+
+    Symfony Env never overwrites existing environment variables.
+
+You should never store a ``.env`` file in your code repository as it might


store an .env file

No, it's store a dot env file :)

Right, thanks!

HeahDude · 2017-01-12T17:56:54Z

components/dotenv.rst

+    Symfony Env never overwrites existing environment variables.
+
+You should never store a ``.env`` file in your code repository as it might
+contain sensitive information; create a ``.env.dist`` file with sensible


an here too

This PR was merged into the 3.3-dev branch. Discussion ---------- Add a new Dotenv component | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | n/a | License | MIT | Doc PR | symfony/symfony-docs#7350 This introduces a new Dotnv Component that manages `.env` files. Read the referenced doc PR above for more information about usage: But here, I want to explain the rationale behind creating such a component instead of reusing an existing one. * First, this version only implements what you can do in a "real" bash shell script (which is what a `.env` really is): so **no value validation** for instance (and anyway, an env var value is always a string). That's important as in production, we should use real env variables, and we don't have validation for them there; * It allows to only parse a file without populating the env variables (we have 3 stages: `load` `parse` and `populate`); * Strict implementation of what you can do in a `.env` file, same behavior as bash ($VAR and ${VAR} are supported for instance, executing commands as well); * Great error messages: I spent a lot of time being sure that error reporting is top notch; * Clean, simple, and straightforward code (small public API); * It only does `.env` management, there is no uneeded abstractions like being able to add an env variable directly (just use `putenv`); There are some unimplemented features as I don't think they are needed and would increase the complexity of the code: several concatenated strings `FOO='foo'"bar"` for instance. Commits ------- 5a6be8a [Dotenv] added the component

fabpot · 2017-01-12T18:17:49Z

This one is ready and the related PR on Symfony has been merged now.

HeahDude · 2017-01-12T18:28:44Z

components/dotenv.rst

+
+Sensitive information and environment-dependent settings should be defined as
+environment variables (as recommended for `twelve-factor applications`_. Using
+an ``.env`` file to store those environment variables eases development and CI


Then it's a here :)

HeahDude · 2017-01-12T18:36:38Z

👍

lyrixx · 2017-01-12T19:23:37Z

components/dotenv.rst

+    PHP has a lot of different implementations of this "pattern". This
+    implementation's goal is to replicate what ``source .env`` would do. So, it
+    tries to be as similar as possible with the default shell's behavior, and
+    does not do anything not possible via ``source`` (like value validation).


Double negation is hard to read

aboks · 2017-01-12T21:32:21Z

components/dotenv.rst

+-----
+
+Sensitive information and environment-dependent settings should be defined as
+environment variables (as recommended for `twelve-factor applications`_. Using


A closing parenthesis is missing on this line.

javiereguiluz

I'm missing a brief explanation about the 3 stages and their purposes: load, parse and populate. Thanks!

sstok · 2017-01-13T09:38:42Z

components/dotenv.rst

+    DB_USER=root
+    DB_PASS=${DB_USER}pass # Include the user as a password prefix
+
+Embed commands via ``$()`` (not supported on Windows):


Windows 10 added support for a Bash shell, so is this is still valid?
Note that I'm not using Windows atm, nor Windows 10 😅

Windows is not able to do it out of the box. But you can use it through an emulator like cmder or ConEmu.

Wait ConEmu support this? Cool :)

Windows 10 added bash support, but using an Ubuntu subsystem 😵 so it will work as expected then.

OskarStark · 2017-01-13T14:34:34Z

components/dotenv.rst

+environment variables (as recommended for `twelve-factor applications`_. Using
+a ``.env`` file to store those environment variables eases development and CI
+management by keeping them in one "standard" place and agnostic of the
+technology stack you are using (Nginx vs PHP built-in server for instance).


nginx instead of Nginx?

I think we use Nginx everywhere else.

indeed, Nginx is used elsewhere

jderusse · 2017-01-14T16:05:18Z

components/dotenv.rst

+
+    The Dotenv Component parses ``.env`` files to make environment variables
+    stored in them accessible via ``getenv()``, ``$_ENV`` or ``$_SERVER``.
+


Shouldn't you add a versionadded section (like in cache and workflow?)

fabpot · 2017-01-14T17:07:14Z

@javiereguiluz The only entry-point should be load for most developers. load is just a shortcut to parse then populate, but using those last 2 directly should be very rare. So, I don't think we need to "document" them here (phpdocs are enough IMHO).

juliendufresne · 2017-01-21T16:58:20Z

components/dotenv.rst

+defaults instead.
+
+Symfony Env should only be used in development/testing/staging environments.
+For production environments, use "real" environment variables.


What do Symfony Env stands for? Does it refer to this component?

Does it mean we should not use this component in production environment?

Fixed, should have been Symfony Dotenv.

Indeed, in production, you should define "real" env vars.

fabpot · 2017-01-21T17:12:30Z

Anything blocking the merge (besides time :))?

teohhanhui · 2017-01-23T08:23:17Z

Regarding the integration with Symfony, it's going to be part of the whole new "bootstrap" experience I'm working on. More on that later.

I hope it'll bring Symfony closer to The Twelve-Factor App (esp. https://12factor.net/config), which will be good news for Docker users. Currently the parameters.yml situation is a bit of a pain (probably improved since dynamic env parameters)...

xabbuh · 2017-01-24T08:38:55Z

Thank you @fabpot.

This PR was merged into the master branch. Discussion ---------- Add docs for the Dotenv component See symfony/symfony#21234 Commits ------- 03fda49 added docs for the env component

carsonbot added the Status: Needs Review label Jan 11, 2017

fabpot mentioned this pull request Jan 11, 2017

Add a new Dotenv component symfony/symfony#21234

Merged

yceruto reviewed Jan 11, 2017

View reviewed changes

components/env.rst

.. code-block:: php

$dbUser = getenv('DB_USER);

Copy link

Member

yceruto Jan 11, 2017

Choose a reason for hiding this comment

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

Missing single quote 'DB_USER'

fabpot force-pushed the env-component branch from bf2911f to 3c767bb Compare January 11, 2017 03:13

w3guy reviewed Jan 11, 2017

View reviewed changes

javiereguiluz approved these changes Jan 11, 2017

View reviewed changes

jakzal reviewed Jan 11, 2017

View reviewed changes

fabpot force-pushed the env-component branch from 3c767bb to b6a8b7f Compare January 11, 2017 18:45

fabpot force-pushed the env-component branch 2 times, most recently from 38a171f to bb181d5 Compare January 11, 2017 23:18

xabbuh added the On hold label Jan 12, 2017

xabbuh reviewed Jan 12, 2017

View reviewed changes

fabpot force-pushed the env-component branch from bb181d5 to 48789e8 Compare January 12, 2017 15:12

carsonbot added Status: Reviewed and removed Status: Needs Review labels Jan 12, 2017

HeahDude reviewed Jan 12, 2017

View reviewed changes

fabpot force-pushed the env-component branch from 48789e8 to 88de480 Compare January 12, 2017 18:16

fabpot removed the On hold label Jan 12, 2017

fabpot changed the title ~~added docs for the env component~~ Add docs for the env component Jan 12, 2017

fabpot changed the title ~~Add docs for the env component~~ Add docs for the Dotenv component Jan 12, 2017

HeahDude reviewed Jan 12, 2017

View reviewed changes

fabpot force-pushed the env-component branch from 88de480 to 8a9cd00 Compare January 12, 2017 18:30

lyrixx reviewed Jan 12, 2017

View reviewed changes

fabpot force-pushed the env-component branch from 8a9cd00 to 14f8d58 Compare January 12, 2017 20:21

aboks reviewed Jan 12, 2017

View reviewed changes

javiereguiluz reviewed Jan 13, 2017

View reviewed changes

sstok reviewed Jan 13, 2017

View reviewed changes

OskarStark reviewed Jan 13, 2017

View reviewed changes

jderusse reviewed Jan 14, 2017

View reviewed changes

fabpot force-pushed the env-component branch from 14f8d58 to 5485046 Compare January 14, 2017 17:08

juliendufresne reviewed Jan 21, 2017

View reviewed changes

added docs for the env component

03fda49

fabpot force-pushed the env-component branch from 5485046 to 03fda49 Compare January 21, 2017 17:11

xabbuh merged commit 03fda49 into symfony:master Jan 24, 2017

javiereguiluz modified the milestone: 3.3 Feb 1, 2017


		Symfony Env never overwrites existing environment variables.

		You should never store a ``.env`` file is your code repository as it might


		.. note::

		PHP has a lot of different implementation of this "pattern". This


		Load an ``.env`` file in your PHP application via ``Dotenv::load()``:

		.. code-block:: php


		You can install the component in 2 different ways:

		* :doc:`Install it via Composer </components/using_components>` (``symfony/env`` on `Packagist`_);


		Given the following ``.env`` file content:

		.. code-block:: bash


		First, require Symfony Dotenv via Composer:

		.. code-block:: bash


		The Dotenv Component parses ``.env`` files to make environment variables
		stored in them accessible via ``getenv()``, ``$_ENV`` or ``$_SERVER``.

Add docs for the Dotenv component #7350

Add docs for the Dotenv component #7350

Conversation

fabpot commented Jan 11, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

javiereguiluz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jakzal Jan 11, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fabpot commented Jan 11, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xabbuh Jan 12, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fabpot commented Jan 12, 2017

xabbuh commented Jan 12, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fabpot commented Jan 12, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HeahDude commented Jan 12, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

javiereguiluz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fabpot commented Jan 14, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fabpot commented Jan 21, 2017

teohhanhui commented Jan 23, 2017 • edited Loading

xabbuh commented Jan 24, 2017

jakzal Jan 11, 2017 •

edited

Loading

xabbuh Jan 12, 2017 •

edited

Loading

teohhanhui commented Jan 23, 2017 •

edited

Loading