Updating docs for a few more .env changes

weaverryan · weaverryan · commit cf245d4b7332 · 2018-12-18T14:45:31.000-05:00
1) .env being always loaded after proposed recipe
2) A new command to dump an optimized version of those env vars
3) A new command to update your recipes
diff --git a/configuration.rst b/configuration.rst
@@ -313,8 +313,7 @@ You can also create a few other ``.env`` files that will be loaded:
   ``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``.
+*are* still loaded, but your real environment variables will override those values.
 
 Environments & the Other Config Files
 -------------------------------------
diff --git a/configuration/dot-env-changes.rst b/configuration/dot-env-changes.rst
@@ -30,19 +30,59 @@ important changes:
   other environments. You can also create a ``.env.test`` file for test-environment
   overrides.
 
-* E) If you pass the ``--env=`` flag when running ``bin/console``, this value will
-  override your ``APP_ENV`` environment variable (if set). And so, if you pass
-  ``--env=prod``, the DotEnv component *will* try to load your ``.env*`` files.
+* E) `One further change to the recipe in December 2019`_ means that your ``.env``
+  files are *always* loaded, even if you set an ``APP_ENV=prod`` environment
+  variable. The purpose is for the ``.env`` files to define default values that
+  you can override if you want to with real environment values.
 
 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:
+First, make sure you're using ``symfony/flex`` version 1.2 or later:
+
+.. code-block:: terminal
+
+    composer update symfony/flex
+
+The easiest way to update your application is to update all of your recipes using
+the :ref:`sync-recipes <updating-recipes>` command. This command will update *all*
+your recipes, so it will probably include other changes beyond the ones needed for
+the new environment handling.
+
+First, 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
+
+Now run:
+
+.. code-block:: terminal
+
+    $ composer sync-recipes --force
+
+If this asks you to overwrite uncommited changes in ``.env``, choose "no" - you
+should keep the values from your ``.env`` file.
+
+When the command finishes, review the changes - there may be extra files or changes
+from other recipes that you don't want. If you made custom changes to files, you'll
+need to use re-add those (hint using ``git diff`` is a great way to see the changes
+made by the recipes).
+
+Summary of the Changes
+~~~~~~~~~~~~~~~~~~~~~~
+
+IF you want to manually update your application, here the details: these changes
+can be made to any Symfony 3.4 or higher app:
 
 #. Create a new `config/bootstrap.php`_ file in your project. This file loads Composer's
    autoloader and loads all the ``.env`` files as needed (note: in an earlier recipe,
@@ -94,3 +134,4 @@ changes can be made to any Symfony 3.4 or higher app:
 .. _`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
+.. _`One further change to the recipe in December 2019`: https://github.com/symfony/recipes/pull/501
diff --git a/deployment.rst b/deployment.rst
@@ -172,7 +172,18 @@ as you normally do:
     using :doc:`Symfony Flex </setup/flex>`) before running this command so
     that the ``post-install-cmd`` scripts run in the ``prod`` environment.
 
-D) Clear your Symfony Cache
+D) Dumping Optimized Environment Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're using Symfony Flex, you can get a small performance boost by running
+a command that reads your ``.env`` files and dumps an optimized ``.env.local.php``
+file that's read by your application:
+
+.. code-block:: terminal
+
+    $ composer dump-env prod
+
+E) Clear your Symfony Cache
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Make sure you clear and warm-up your Symfony cache:
@@ -181,7 +192,7 @@ Make sure you clear and warm-up your Symfony cache:
 
     $ php bin/console cache:clear --env=prod --no-debug
 
-E) Other Things!
+F) Other Things!
 ~~~~~~~~~~~~~~~~
 
 There may be lots of other things that you need to do, depending on your
diff --git a/quick_tour/the_architecture.rst b/quick_tour/the_architecture.rst
@@ -288,9 +288,8 @@ as *environment* variables. This means that Symfony works *perfectly* with
 Platform as a Service (PaaS) deployment systems as well as Docker.
 
 But setting environment variables while developing can be a pain. That's why your
-app automatically loads a ``.env`` file, if the ``APP_ENV`` environment variable
-isn't set in the environment. The keys in this file then become environment variables
-and are read by your app:
+app automatically loads a ``.env`` file. The keys in this file then become environment
+variables and are read by your app:
 
 .. code-block:: bash
 
diff --git a/setup/_update_flex_recipes.rst.inc b/setup/_update_flex_recipes.rst.inc
@@ -0,0 +1,8 @@
+Upgrading Flex Recipes
+~~~~~~~~~~~~~~~~~~~~~~
+
+Some :doc:`Flex Recipes </setup/flex>` for packages you've already installed may
+also be out of date. You don't need to update these, but it's a great way to keep
+your code updated with the latest features and conventions.
+
+See :ref:`updating-recipes` for details.
diff --git a/setup/flex.rst b/setup/flex.rst
@@ -51,6 +51,34 @@ SwiftmailerBundle and returns the "recipe" for it.
 Flex keeps tracks of the recipes it installed in a ``symfony.lock`` file, which
 must be committed to your code repository.
 
+.. _updating-recipes:
+
+Updating Recipes
+~~~~~~~~~~~~~~~~
+
+Over time, recipes for packages you've already installed might be updated. Your app
+doesn't need these updated recipes to function, but you may want to apply the updates
+to take advantage of the latest features and conventions.
+
+To do this, you can tell Flex to "sync" the recipes. This means it will apply the
+latest recipe version for each package and **overwrite** any existing files. Make
+sure you've committed all your files to git, and then run:
+
+.. code-block:: terminal
+
+    $ composer sync-recipes --force
+
+.. versionadded:: 1.2
+    The ``sync-recipes --force`` command was introduced in symfony/flex 1.2.0.
+
+The command will ask you before overwriting any files with uncommitted changes.
+
+The tricky part about updating recipes is that you may not want or need many of
+the changes. Often a recipe will add a new file to help get you started, which
+you may not need. Feel free to delete any "extra" files you don't need, or revert
+any changes you don't want. Recipes are generally a great "starting" point - and
+your app will naturally evolve how it needs to.
+
 Symfony Flex Recipes
 ~~~~~~~~~~~~~~~~~~~~
 
diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst
@@ -160,4 +160,6 @@ When upgrading to Symfony 4, you will probably also want to upgrade to the new
 Symfony 4 directory structure so that you can take advantage of Symfony Flex.
 This takes some work, but is optional. For details, see :ref:`upgrade-to-flex`.
 
+.. include:: /setup/_update_flex_recipes.rst.inc
+
 .. _`Symfony-Upgrade-Fixer`: https://github.com/umpirsky/Symfony-Upgrade-Fixer
diff --git a/setup/upgrade_minor.rst b/setup/upgrade_minor.rst
@@ -69,5 +69,7 @@ safe to update in the future.
 
 These documents can also be found in the `Symfony Repository`_.
 
+.. include:: /setup/_update_flex_recipes.rst.inc
+
 .. _`Symfony Repository`: https://github.com/symfony/symfony
 .. _`UPGRADE-4.1.md`: https://github.com/symfony/symfony/blob/4.1/UPGRADE-4.1.md
diff --git a/setup/upgrade_patch.rst b/setup/upgrade_patch.rst
@@ -20,3 +20,5 @@ always safe to upgrade to the latest "minor" version.
     releases.
 
 .. include:: /setup/_update_all_packages.rst.inc
+
+.. include:: /setup/_update_flex_recipes.rst.inc
