Merge pull request #7401 from kenjis/docs-improve-environments

docs: improve environments

user_guide_src/source/general/configuration.rst

@@ -63,6 +63,8 @@ One of today's best practices for application setup is to use Environment Variab
 
 Environment Variables should also be used for anything private such as passwords, API keys, or other sensitive data.
 
+.. _dotenv-file:
+
 Environment Variables and CodeIgniter
 =====================================
 

user_guide_src/source/general/environments.rst

@@ -11,29 +11,44 @@ tools loaded that you don't in production environments, etc.
 
 .. contents::
     :local:
-    :depth: 2
+    :depth: 3
+
+************************
+The Defined Environments
+************************
+
+By default, CodeIgniter has three environments defined.
+
+- ``production`` for production
+- ``development`` for development
+- ``testing`` for PHPUnit testing
+
+.. important:: The environment ``testing`` is reserved for PHPUnit testing. It
+    has special conditions built into the framework at various places to assist
+    with that. You can't use it for your development.
+
+If you want another environment, e.g., for staging, you can add custom environments.
+See `Adding Environments`_.
+
+*******************
+Setting Environment
+*******************
 
 .. _environment-constant:
 
 The ENVIRONMENT Constant
 ========================
 
-By default, CodeIgniter comes with the ``ENVIRONMENT`` constant set to use
-the value provided in ``$_SERVER['CI_ENVIRONMENT']``, otherwise defaulting to
-``production``. This can be set in several ways depending on your server setup.
-
-.. note:: The environment ``testing`` is the special one for PHPUnit testing.
-    It has special conditions built into the framework at various places to assist with that.
-    You can't use it for your development.
+To set your environment, CodeIgniter comes with the ``ENVIRONMENT`` constant.
+If you set ``$_SERVER['CI_ENVIRONMENT']``, the value will be used,
+otherwise defaulting to ``production``.
 
-.. note:: You can check the current environment by ``spark env`` command::
-
-    > php spark env
+This can be set in several ways depending on your server setup.
 
 .env
 ----
 
-The simplest method to set the variable is in your :doc:`.env file </general/configuration>`.
+The simplest method to set the variable is in your :ref:`.env file <dotenv-file>`.
 
 .. code-block:: ini
 
@@ -88,8 +103,14 @@ In addition to affecting some basic framework behavior (see the next
 section), you may use this constant in your own development to
 differentiate between which environment you are running in.
 
+*******************
+Adding Environments
+*******************
+
+To add custom environments, you just need to add boot files for them.
+
 Boot Files
-----------
+==========
 
 CodeIgniter requires that a PHP script matching the environment's name is located
 under **APPPATH/Config/Boot**. These files can contain any customizations that
@@ -102,15 +123,32 @@ a fresh install:
 * production.php
 * testing.php
 
+For example, if you want to add ``staging`` environment for staging, all you need
+to do is:
+
+1. copy **APPPATH/Config/Boot/production.php** to **staging.php**.
+2. customize settings in **staging.php** if you want.
+
+**********************************
+Confirming the Current Environment
+**********************************
+
+To confirm the current environment, simply echo the constant ``ENVIRONMENT``.
+
+You can also check the current environment by ``spark env`` command::
+
+    > php spark env
+
+*************************************
 Effects on Default Framework Behavior
-=====================================
+*************************************
 
 There are some places in the CodeIgniter system where the ``ENVIRONMENT``
 constant is used. This section describes how default framework behavior
 is affected.
 
 Error Reporting
----------------
+===============
 
 Setting the ``ENVIRONMENT`` constant to a value of ``development`` will cause
 all PHP errors to be rendered to the browser when they occur.