From d2cef240975ec1301a5640e1e255fe718a4d2c7d Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 27 Jul 2017 22:33:14 -0400 Subject: [PATCH 1/2] Add documentation for environment variables. Shuffle sections around so environment variables are higher up. --- en/appendices/3-5-migration-guide.rst | 7 +++ en/development/configuration.rst | 78 ++++++++++++++------------- 2 files changed, 47 insertions(+), 38 deletions(-) diff --git a/en/appendices/3-5-migration-guide.rst b/en/appendices/3-5-migration-guide.rst index 0635f8bd01..d142c30fca 100644 --- a/en/appendices/3-5-migration-guide.rst +++ b/en/appendices/3-5-migration-guide.rst @@ -175,6 +175,13 @@ 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. + Core ---- diff --git a/en/development/configuration.rst b/en/development/configuration.rst index ac1deef75e..72ed620ee3 100644 --- a/en/development/configuration.rst +++ b/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 `_. +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 +`_ 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 `_ 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 `_ to use -environment variables in a local development. See the Readme instructions of the -library for more information. - Disabling Generic Tables ======================== From 83bb7a3118abfce5ac79487025eedf135517c78d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20W=C3=BCrth?= Date: Fri, 28 Jul 2017 12:33:30 +0200 Subject: [PATCH 2/2] Added is not an important word in the title --- en/appendices/3-5-migration-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/appendices/3-5-migration-guide.rst b/en/appendices/3-5-migration-guide.rst index d142c30fca..03b322cf50 100644 --- a/en/appendices/3-5-migration-guide.rst +++ b/en/appendices/3-5-migration-guide.rst @@ -175,7 +175,7 @@ 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 +dotenv Support added to Application Skeleton -------------------------------------------- The application skeleton now features a 'dotenv' integration making it easier to