Add documentation for environment variables.

en/appendices/3-5-migration-guide.rst

@@ -175,12 +175,20 @@ cache configuration to fall back to if the engine is misconfigured (or
 unavailable). See :ref:`cache-configuration-fallback` for more information on
 configuring fallbacks.
 
+dotenv Support added to Application Skeleton
+--------------------------------------------
+
+The application skeleton now features a 'dotenv' integration making it easier to
+use environment variables to configure your application. See the
+:ref:`environment-variables` section for more information.
+
 Collection
 ----------
 
 * ``Cake\Collection\Collection::avg()`` was added.
 * ``Cake\Collection\Collection::median()`` was added.
 
+
 Core
 ----
 

en/development/configuration.rst

@@ -215,6 +215,46 @@ Inflection Configuration
 
 See the :ref:`inflection-configuration` docs for more information.
 
+.. _environment-variables:
+
+Environment Variables
+=====================
+
+Many modern cloud providers, like Heroku, let you define environment
+variables for configuration data. You can configure your CakePHP through
+environment variables in the `12factor app style <http://12factor.net/>`_.
+Environment variables allow your application to require less state making your
+application easier to manage when it is deployed across a number of
+environments.
+
+As you can see in your **app.php**, the ``env()`` function is used to read
+configuration from the environment, and build the application configuration.
+CakePHP uses :term:`DSN` strings for databases, logs, email transports and cache
+configurations allowing you to easily vary these libraries in each environment.
+
+For local development, CakePHP leverages `dotenv
+<https://github.com/josegonzalez/dotenv>`_ to allow easy local development using
+environment variables. You will see a ``config/.env.default`` in your
+application. By copying this file into ``config/.env`` and customizing the
+values you can configure your application.
+
+You should avoid committing the ``config/.env`` file to your repository and
+instead use the ``config/.env.default`` as a template with placeholder values so
+everyone on your team knows what environment variables are in use and what
+should go in each one.
+
+Once your environment variables have been set, you can use ``env()`` to read
+data from the environment::
+
+    $debug = env('APP_DEBUG', false);
+
+The second value passed to the env function is the default value. This value
+will be used if no environment variable exists for the given key.
+
+.. versionchanged:: 3.5.0
+    dotenv library support was added to the application skeleton.
+
+
 Configure Class
 ===============
 
@@ -328,7 +368,6 @@ Read and delete a key from Configure. This is useful when you want to
 combine reading and deleting values in a single operation.
 
 
-
 Reading and writing configuration files
 =======================================
 
@@ -645,43 +684,6 @@ Loading plugins/events in ``Application::bootstrap()`` makes
 :ref:`integration-testing` easier as events and routes will be re-processed on
 each test method.
 
-Environment Variables
-=====================
-
-Some of the modern cloud providers, like Heroku, let you define environment
-variables. By defining environment variables, you can configure your CakePHP
-app as an 12factor app. Following the
-`12factor app instructions <http://12factor.net/>`_ is a good way to create a
-stateless app, and to ease the deployment of your app.
-This means for example, that if you need to change your database, you'll just
-need to modify a DATABASE_URL variable on your host configuration without the
-need to change it in your source code.
-
-As you can see in your **app.php**, the following variables are concerned:
-
-- ``DEBUG`` (``0`` or ``1``)
-- ``APP_ENCODING`` (ie UTF-8)
-- ``APP_DEFAULT_LOCALE`` (ie ``en_US``)
-- ``SECURITY_SALT``
-- ``CACHE_DEFAULT_URL`` (ie ``File:///?prefix=myapp_&serialize=true&timeout=3600&path=../tmp/cache/``)
-- ``CACHE_CAKECORE_URL`` (ie ``File:///?prefix=myapp_cake_core_&serialize=true&timeout=3600&path=../tmp/cache/persistent/``)
-- ``CACHE_CAKEMODEL_URL`` (ie ``File:///?prefix=myapp_cake_model_&serialize=true&timeout=3600&path=../tmp/cache/models/``)
-- ``EMAIL_TRANSPORT_DEFAULT_URL`` (ie ``smtp://user:password@hostname:port?tls=null&client=null&timeout=30``)
-- ``DATABASE_URL`` (ie ``mysql://user:pass@db/my_app``)
-- ``DATABASE_TEST_URL`` (ie ``mysql://user:pass@db/test_my_app``)
-- ``LOG_DEBUG_URL`` (ie ``file:///?levels[]=notice&levels[]=info&levels[]=debug&file=debug&path=../logs/``)
-- ``LOG_ERROR_URL`` (ie ``file:///?levels[]=warning&levels[]=error&levels[]=critical&levels[]=alert&levels[]=emergency&file=error&path=../logs/``)
-
-As you can see in the examples, we define some options configuration as
-:term:`DSN` strings. This is the case for databases, logs, email transport and
-cache configurations.
-
-If the environment variables are not defined in your environment, CakePHP will
-use the values that are defined in the **app.php**. You can use
-`php-dotenv library <https://github.com/josegonzalez/php-dotenv>`_ to use
-environment variables in a local development. See the Readme instructions of the
-library for more information.
-
 Disabling Generic Tables
 ========================