From aa69cfe497b7adc1ae41f9376431cbcaa6721b7a Mon Sep 17 00:00:00 2001
From: Damian Mooyman <damian@silverstripe.com>
Date: Thu, 23 Feb 2017 16:01:59 +1300
Subject: [PATCH] Improve upgrading guide for `.env`

---
 docs/en/04_Changelogs/4.0.0.md | 67 +++++++++++++++++++++++++---------
 1 file changed, 50 insertions(+), 17 deletions(-)

diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md
index f7a341e6e..921f3d3da 100644
--- a/docs/en/04_Changelogs/4.0.0.md
+++ b/docs/en/04_Changelogs/4.0.0.md
@@ -105,6 +105,56 @@ the `SilverStripe\Forms` namespace.
 The below sections deal with upgrades to specific parts of various API. Projects which rely on certain
 API should be upgraded as appropriate using any of the relevant processes documented below.
 
+#### Upgrade of `_ss_environment.php` to `.env` configuration
+
+The php configuration `_ss_environment.php` file has been replaced in favour of a non-executable
+`.env` file, which follows a syntax similar to an `.ini` file for key/value pair assignment. Like
+the old php file, `.env` may be placed in either the web root, or one level above.
+
+For example, if you have the below `_ss_environment.php` file, your `.env` would be rewritten as follows:
+
+`_ss_environment.php`:
+
+
+    :::php
+    <?php
+    // Environment
+    define('SS_ENVIRONMENT_TYPE', 'dev');
+    define('SS_DEFAULT_ADMIN_USERNAME', 'admin');
+    define('SS_DEFAULT_ADMIN_PASSWORD', 'password');
+    $_FILE_TO_URL_MAPPING[__DIR__] = 'http://localhost';
+    // Database
+    define('SS_DATABASE_CHOOSE_NAME', true);
+    define('SS_DATABASE_CLASS', 'MySQLDatabase');
+    define('SS_DATABASE_USERNAME', 'root')
+    define('SS_DATABASE_PASSWORD', '');
+    define('SS_DATABASE_SERVER', '127.0.0.1');
+
+    
+`.env`:
+
+
+    ## Environment
+    SS_ENVIRONMENT_TYPE="dev"
+    SS_DEFAULT_ADMIN_USERNAME="admin"
+    SS_DEFAULT_ADMIN_PASSWORD="password"
+    SS_HOST="localhost"
+    ### Database
+    SS_DATABASE_CHOOSE_NAME="true"
+    SS_DATABASE_CLASS="MySQLDatabase"
+    SS_DATABASE_USERNAME="root"
+    SS_DATABASE_PASSWORD=""
+    SS_DATABASE_SERVER="127.0.0.1"
+
+
+The removal of the `_ss_environment.php` file means that conditional logic is no longer available in the environment
+variable set-up process. This generally encouraged bad practice and should be avoided. If you still require conditional
+logic early in the bootstrap, this is best placed in the `_config.php` files.
+
+Note also that `$_FILE_TO_URL_MAPPING` has been removed and replaced with `SS_HOST` env var.
+
+See [Environment Management docs](/getting-started/environment_management/) for full details.
+
 #### Compatibility with the new front-end building tools
 
 If you are using Requirements from 3.x then your scripts should continue to work as they did before.
@@ -1434,20 +1484,3 @@ New `TimeField` methods replace `getConfig()` / `setConfig()`
 * `$email->setTemplate()` renamed to `$email->setHTMLTemplate()`
 * Added `$email->setPlainTemplate` for rendering plain versions of email
 * `$email->populateTemplate()` has been replaced with `$email->setData()`
-
-
-### <a name="overview-environment-management"></a>Environment management
-
-See [Environment Management docs](https://docs.silverstripe.org/en/4/getting_started/environment_management/) for full
-details.
-
-The removal of the `_ss_environment.php` file means that conditional logic is no longer available in the environment
-varialbe set-up process. This generally encouraged bad practice and should be avoided. If you still require conditional
-logic early in the bootstrap, this is best placed in the `_config.php` files.
-
-#### Environment file changes
-
-* Removed support for _ss_environment.php in favour of .env and first class environment variables
-* Environment variables now can be set in `.env` file placed in webroot or one level above
-* Environment variables will be read from the environment as well
-* `$_FILE_TO_URL_MAPPING` has been removed and replaced with using `Director.alternate_host` or `SS_HOST` env var