From a49109f32ef4de3d323ef6e97af3b2ed1a866c97 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Thu, 15 Nov 2018 11:49:26 -0500 Subject: [PATCH] updating docs for .env changes --- best_practices/configuration.rst | 22 +++++--- configuration.rst | 46 +++++++++++----- configuration/dot-env-changes.rst | 91 +++++++++++++++++++++++++++++++ configuration/environments.rst | 14 ++--- deployment.rst | 8 +-- doctrine.rst | 2 +- doctrine/dbal.rst | 2 +- doctrine/reverse_engineering.rst | 2 +- email.rst | 2 + quick_tour/the_big_picture.rst | 1 - security/force_https.rst | 2 +- testing.rst | 40 ++++++++++---- 12 files changed, 181 insertions(+), 51 deletions(-) create mode 100644 configuration/dot-env-changes.rst diff --git a/best_practices/configuration.rst b/best_practices/configuration.rst index 576bf30157c..f1424abf0a3 100644 --- a/best_practices/configuration.rst +++ b/best_practices/configuration.rst @@ -19,7 +19,8 @@ application behavior. Define the infrastructure-related configuration options as :doc:`environment variables `. During - development, use the ``.env`` file at the root of your project to set these. + development, use the ``.env`` and ``.env.local`` files at the root of your project + to set these. By default, Symfony adds these types of options to the ``.env`` file when installing new dependencies in the app: @@ -42,6 +43,9 @@ they have nothing to do with the application's behavior. In other words, your application doesn't care about the location of your database or the credentials to access to it, as long as the database is correctly configured. +To override these variables with machine-specific or sensitive values, create a +``env.local`` file. This file should not be added to version control. + .. caution:: Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables @@ -56,14 +60,18 @@ Canonical Parameters .. best-practice:: - Define all your application's env vars in the ``.env.dist`` file. + Define all your application's env vars in the ``.env`` file. + +Symfony includes a configuration file called ``.env`` at the project root, which +stores the canonical list of environment variables for the application. This +file should be stored in version control and so should only contain non-sensitive +default values. -Symfony includes a configuration file called ``.env.dist`` at the project root, -which stores the canonical list of environment variables for the application. +.. caution:: -Whenever a new env var is defined for the application, you should also add it to -this file and submit the changes to your version control system so your -workmates can update their ``.env`` files. + Applications created before November 2018 had a slightly different system, + involving a ``.env.dist`` file. For information about upgrading, see: + :doc:`/configuration/dot-env-changes`. Application-Related Configuration --------------------------------- diff --git a/configuration.rst b/configuration.rst index aea434c2f3f..10a56896b48 100644 --- a/configuration.rst +++ b/configuration.rst @@ -263,10 +263,12 @@ a controller - see :ref:`service-container-parameters`. The .env File & Environment Variables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There is also a ``.env`` file which is loaded. Its contents become environment -variables in the dev environment, making it easier to reference environment -variables in your code. When you install packages, more environment variables are -added to this file. But you can also add your own variables. +There is also a ``.env`` file which is loaded and its contents become environment +variables. This is useful during development, or if setting environment variables +is difficult for your deployment. + +When you install packages, more environment variables are added to this file. But +you can also add your own. Environment variables can be referenced in any other configuration files by using a special syntax. For example, if you install the ``doctrine`` package, then you @@ -285,18 +287,34 @@ This is referenced inside ``config/packages/doctrine.yaml``: For more details about environment variables, see :ref:`config-env-vars`. +.. caution:: + + Applications created before November 2018 had a slightly different system, + involving a ``.env.dist`` file. For information about upgrading, see: + :doc:`configuration/dot-env-changes`. + The ``.env`` file is special, because it defines the values that usually change on each server. For example, the database credentials on your local development -machine might be different from your workmates. That's why this file is **not -committed to the shared repository** and is only stored on your machine. In -fact, the ``.gitignore`` file that comes with Symfony prevents it from being -committed. - -However, a ``.env.dist`` file *is* committed (with dummy values). This file -isn't read by Symfony: it's just a reference so that Symfony knows which -variables need to be defined in the ``.env`` file. If you add or remove keys to -``.env``, add or remove them from ``.env.dist`` too, so both files are always -in sync. +machine might be different from your workmates. The ``.env`` file should contain +sensible, non-secret *default* values for all of your environment variables and +*should* be commited to your repository. + +To override these variables with machine-specific or sensitive values, create a +``env.local`` file. This file is **not committed to the shared repository** and +is only stored on your machine. In fact, the ``.gitignore`` file that comes with +Symfony prevents it from being committed. + +You can also create a few other ``.env`` files that will be loaded: + +* ``.env.{environment}``: e.g. ``.env.test`` will be loaded in the ``test`` environment + and committed to your repository. + +* ``.env.{environment}.local``: e.g. ``.env.prod.local`` will be loaded in the + ``prod`` environment but will *not* be committed to your repository. + +If you decide to set real environment variables on production, the ``.env`` files +will *not* be loaded if Symfony detects that a real ``APP_ENV`` environment variable +exists and is set to ``prod``. Environments & the Other Config Files ------------------------------------- diff --git a/configuration/dot-env-changes.rst b/configuration/dot-env-changes.rst new file mode 100644 index 00000000000..748472aa5a7 --- /dev/null +++ b/configuration/dot-env-changes.rst @@ -0,0 +1,91 @@ +Nov 2018 Changes to .env & How to Update +======================================== + +In November 2018, several changes were made to the core Symfony *recipes* related +to the ``.env`` file. These changes make working with environment variables easier +and more consistent - especially when writing functional tests. + +If your app was started before November 2018, your app **does not require any changes +to keep working**. However, if/when you are ready to take advantage of these improvements, +you will need to make a few small updates. + +What Changed Exactly? +--------------------- + +But first, what changed? On a high-level, not much. Here's a summary of the most +important changes: + +* A) The ``.env.dist`` file no longer exists. Its contents should be moved to your + ``.env`` file (see the next point). + +* B) The ``.env`` file **is** now commited to your repository. It was previously ignored + via the ``.gitignore`` file (the updated recipe does not ignore this file). Because + this file is committed, it should contain non-sensitive, default values. Basically, + the ``.env.dist`` file was moved to ``.env``. + +* C) A ``.env.local`` file can now be created to *override* environment variables for + your machine. This file is ignored in the new ``.gitignore``. + +* D) When testing, your ``.env`` file is now read, making it consistent with all + other environments. You can also create a ``.env.test`` file for test-environment + overrides. + +There are a few other improvements, but these are the most important. To take advantage +of these, you *will* need to modify a few files in your existing app. + +Updating My Application +----------------------- + +If you created your application after November 15th 2018, you don't need to make +any changes! Otherwise, here is the list of changes you'll need to make - these +changes can be made to any Symfony 3.4 or higher app: + +#. Create a new `src/.bootstrap.php`_ file in your project. This file loads Composer's + autoloader and loads all the ``.env`` files as needed. + +#. Update your `public/index.php`_ (`index.php diff`_) file to load the new ``src/.bootstrap.php`` + file. If you've customized this file, make sure to keep those changes (but use + the rest of the changes). + +#. Update your `bin/console`_ (`bin/console diff`_) file to load the new ``src/.bootstrap.php`` file. + +#. Update ``.gitignore``: + + .. code-block:: diff + + # .gitignore + # ... + + ###> symfony/framework-bundle ### + - /.env + + /.env.local + + /.env.*.local + + # ... + +#. Rename ``.env`` to ``.env.local`` and ``.env.dist`` to ``.env``: + + .. code-block:: terminal + + # Unix + $ mv .env .env.local + $ git mv .env.dist .env + + # Windows + $ mv .env .env.local + $ git mv .env.dist .env + + You can also update the `comment on the top of .env`_ to reflect the new changes. + +#. If you're using PHPUnit, you will also need to `create a new .env.test`_ file + and update your `phpunit.xml.dist file`_ so it loads the ``src/.bootstrap.php`` + file. + +.. _`src/.bootstrap.php`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/src/.bootstrap.php +.. _`public/index.php`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/public/index.php +.. _`index.php diff`: https://github.com/symfony/recipes/compare/8a4e5555e30d5dff64275e2788a901f31a214e79...86e2b6795c455f026e5ab0cba2aff2c7a18511f7#diff-473fca613b5bda15d87731036cb31586 +.. _`bin/console`: https://github.com/symfony/recipes/blob/master/symfony/console/3.3/bin/console +.. _`bin/console diff`: https://github.com/symfony/recipes/compare/8a4e5555e30d5dff64275e2788a901f31a214e79...86e2b6795c455f026e5ab0cba2aff2c7a18511f7#diff-2af50efd729ff8e61dcbd936cf2b114b +.. _`comment on the top of .env`: https://github.com/symfony/recipes/blob/master/symfony/flex/1.0/.env +.. _`create a new .env.test`: https://github.com/symfony/recipes/blob/master/symfony/phpunit-bridge/3.3/.env.test +.. _`phpunit.xml.dist file`: https://github.com/symfony/recipes/blob/master/symfony/phpunit-bridge/3.3/phpunit.xml.dist diff --git a/configuration/environments.rst b/configuration/environments.rst index a2fd462f6e5..6e45a90a7bd 100644 --- a/configuration/environments.rst +++ b/configuration/environments.rst @@ -80,11 +80,11 @@ Executing an Application in different Environments -------------------------------------------------- To execute the application in each environment, change the ``APP_ENV`` -environment variable. During development, this is done in ``.env``: +environment variable. During development, this is done in ``.env`` or in ``.env.local``: .. code-block:: bash - # .env + # .env or .env.local APP_ENV=dev # or for test: @@ -95,7 +95,7 @@ your application in the configured environment. .. tip:: - In production, it is recommended to configure the environment variables in + In production, you can use real environment variables via your :ref:`web server configuration `. .. note:: @@ -109,14 +109,10 @@ the environment variable is passed to the kernel:: // public/index.php // ... - $kernel = new Kernel($_SERVER['APP_ENV'] ?? 'dev', $_SERVER['APP_DEBUG'] ?? false); + $kernel = new Kernel($_SERVER['APP_ENV'], $_SERVER['APP_DEBUG']); // ... -You can also replace ``$_SERVER['APP_ENV'] ?? 'dev'`` by just ``'dev'`` to -always run the application in the dev environment, independent of the -``APP_ENV`` variable. - .. note:: The ``test`` environment is used when writing functional tests and is @@ -251,7 +247,7 @@ environment through your browser: .. code-block:: bash - # .env + # .env or .env.local APP_ENV=benchmark .. sidebar:: Importing configuration diff --git a/deployment.rst b/deployment.rst index a663c8bb857..088a260a628 100644 --- a/deployment.rst +++ b/deployment.rst @@ -125,21 +125,21 @@ B) Configure your Environment Variables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Most Symfony applications read their configuration from environment variables. -While developing locally, you'll usually store these in a ``.env`` file. On production, -you have two options: +While developing locally, you'll usually store these in ``.env`` and ``.env.local`` +(for local overrides). On production, you have two options: 1. Create "real" environment variables. How you set environment variables, depends on your setup: they can be set at the command line, in your Nginx configuration, or via other methods provided by your hosting service. -2. Or, create a ``.env`` file just like your local development (see note below) +2. Or, create a ``.env.local`` file just like your local development (see note below) There is no significant advantage to either of the two options: use whatever is most natural in your hosting environment. .. note:: - If you use the ``.env`` file on production, you may need to move your + If you use the ``.env.*`` files on production, you may need to move your ``symfony/dotenv`` dependency from ``require-dev`` to ``require`` in ``composer.json``: .. code-block:: terminal diff --git a/doctrine.rst b/doctrine.rst index c5f183f1eaa..59575958ec3 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -39,7 +39,7 @@ The database connection information is stored as an environment variable called .. code-block:: text - # .env + # .env (or override DATABASE_URL in .env.local to avoid committing your changes) # customize this line! DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name" diff --git a/doctrine/dbal.rst b/doctrine/dbal.rst index e4f253237b2..252010e1a46 100644 --- a/doctrine/dbal.rst +++ b/doctrine/dbal.rst @@ -31,7 +31,7 @@ Then configure the ``DATABASE_URL`` environment variable in ``.env``: .. code-block:: text - # .env + # .env (or override DATABASE_URL in .env.local to avoid committing your changes) # customize this line! DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name" diff --git a/doctrine/reverse_engineering.rst b/doctrine/reverse_engineering.rst index 5845c4e8485..761b2694af2 100644 --- a/doctrine/reverse_engineering.rst +++ b/doctrine/reverse_engineering.rst @@ -47,7 +47,7 @@ to a post record thanks to a foreign key constraint. ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci; Before diving into the recipe, be sure your database connection parameters are -correctly setup in the ``.env`` file. +correctly setup in the ``.env`` file (or ``.env.local`` override file). The first step towards building entity classes from an existing database is to ask Doctrine to introspect the database and generate the corresponding diff --git a/email.rst b/email.rst index d136265a59e..c90ff1f6a32 100644 --- a/email.rst +++ b/email.rst @@ -34,6 +34,8 @@ environment variable in the ``.env`` file: .. code-block:: bash + # .env (or override MAILER_URL in .env.local to avoid committing your changes) + # use this to disable email delivery MAILER_URL=null://localhost diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index b81ce88157d..9f6c3ae8f38 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -29,7 +29,6 @@ Symfony application: quick_tour/ ├─ .env - ├─ .env.dist ├─ bin/console ├─ composer.json ├─ composer.lock diff --git a/security/force_https.rst b/security/force_https.rst index cee83d6dab0..91eec81064c 100644 --- a/security/force_https.rst +++ b/security/force_https.rst @@ -80,7 +80,7 @@ access control: To make life easier while developing, you can also use an environment variable, like ``requires_channel: '%env(SECURE_SCHEME)%'``. In your ``.env`` file, set -``SECURE_SCHEME`` to ``http`` locally, but ``https`` on production. +``SECURE_SCHEME`` to ``http`` by default, but override it to ``https`` on production. See :doc:`/security/access_control` for more details about ``access_control`` in general. diff --git a/testing.rst b/testing.rst index 04108b99283..73ed0542813 100644 --- a/testing.rst +++ b/testing.rst @@ -179,18 +179,7 @@ As an example, a test could look like this:: To run your functional tests, the ``WebTestCase`` class needs to know which is the application kernel to bootstrap it. The kernel class is usually defined in the ``KERNEL_CLASS`` environment variable (included in the - default ``phpunit.xml.dist`` file provided by Symfony): - - .. code-block:: xml - - - - - - - - - + default ``.env.test`` file provided by Symfony): If your use case is more complex, you can also override the ``createKernel()`` or ``getKernelClass()`` methods of your functional test, @@ -939,6 +928,33 @@ method:: 'debug' => false, )); +Customizing Database URL / Environment Variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to customize some environment variables for your tests (e.g. the +``DATABASE_URL`` used by Doctrine), you can do that by overriding anything you +need in your ``.env.test`` file: + +.. code-block:: text + + # .env.test + DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name_test" + + # use SQLITE + # DATABASE_URL="sqlite:///%kernel.project_dir%/var/app.db" + +This file is automatically read in the ``test`` environment: any keys here override +the defaults in ``.env``. + +.. caution:: + + Applications created before November 2018 had a slightly different system, + involving a ``.env.dist`` file. For information about upgrading, see: + :doc:`configuration/dot-env-changes`. + +Sending Custom Headers +~~~~~~~~~~~~~~~~~~~~~~ + If your application behaves according to some HTTP headers, pass them as the second argument of ``createClient()``::