DOCS Updated environment management docs to use .env file

docs/en/00_Getting_Started/01_Installation/03_Windows.md

@@ -38,7 +38,7 @@ $ composer create-project silverstripe/installer ./silverstripe
 * Rename the unpacked directory from `C:\wamp\www\silverstripe-vX.X.X` to `C:\wamp\www\silverstripe`
 
 ## Install and configure
-* Option 1: Environment file - Set up a file named _ss_environment.php either in the webroot or a directory above webroot and setup as per the [Environment Management process](/getting_started/environment_management).
+* Option 1: Environment file - Set up a file named `.env` file either in the webroot and setup as per the [Environment Management process](/getting_started/environment_management).
 
 * Option 2: Installer - Visit `http://localhost/silverstripe` - you will see SilverStripe's installation screen.
 * You should be able to click "Install SilverStripe" and the installer will do its thing.  It takes a minute or two.

docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Windows_IIS7.md

@@ -160,22 +160,21 @@ You will need to give **Modify** permission to **IUSR** user. To do it right cli
 
 Now that we've got the backend server software sorted out, it's time to install the SilverStripe CMS/framework.
 
-Create a new file called **_ss_environment.php** in **C:\inetpub\wwwroot**
+Create a new file called `.env` in **C:\inetpub\wwwroot\ss**
 
 This file tells SilverStripe projects installed on this machine which database server and credentials, as well as anything environment specific.
 
-Inside the newly created _ss_environment.php file, insert the following code:
+Inside the newly created `.env` file, insert the following code:
 
-	<?php
-	/* What kind of environment is this: development, test, or live (ie, production)? */
-	define('SS_ENVIRONMENT_TYPE', 'dev');
-	/* Database connection */
-	define('SS_DATABASE_SERVER', 'localhost');
-	define('SS_DATABASE_USERNAME', 'sa');
-	define('SS_DATABASE_PASSWORD', '');
-	/* Configure a default username and password to access the CMS on all sites in this environment */
-	define('SS_DEFAULT_ADMIN_USERNAME', 'username');
-	define('SS_DEFAULT_ADMIN_PASSWORD', 'password');
+	# What kind of environment is this: development, test, or live (ie, production)?
+    SS_ENVIRONMENT_TYPE="dev";
+	# Database connection
+	SS_DATABASE_SERVER="localhost"
+	SS_DATABASE_USERNAME="sa"
+	SS_DATABASE_PASSWORD=""
+	# Configure a default username and password to access the CMS on all sites in this environment
+	SS_DEFAULT_ADMIN_USERNAME="username"
+	SS_DEFAULT_ADMIN_PASSWORD="password"
 
 Insert the password you created for SQL Server earlier into the **SS_DATABASE_PASSWORD** field that is currently empty.
 
@@ -211,7 +210,7 @@ If all goes to plan, you're done, and you should see a basic template with a few
 
 Most of the time, it's caused by a loaded PHP extension that is broken.
 
-  * Have you set up the MSSQL database details correctly in _ss_environment.php?
+  * Have you set up the MSSQL database details correctly in `.env` file?
   * Have you made IIS expose errors? (see "How do I make IIS expose errors..." below)
   * Are you running non-standard PHP extensions? If so, try unloading them one by one
   * Make sure you're using the latest [[http://www.microsoft.com/downloads/en/details.aspx?FamilyID=80E44913-24B4-4113-8807-CAAE6CF2CA05&displaylang=en/|Microsoft Drivers for PHP for SQL Server]]

docs/en/00_Getting_Started/02_Composer.md

@@ -129,20 +129,18 @@ Since SilverStripe modules are installed into their own folder, you have to mana
 
 Here is the default SilverStripe [.gitignore](http://git-scm.com/docs/gitignore) with the forum module ignored
 
-```
-assets/*
-_ss_environment.php
-tools/phing-metadata
-silverstripe-cache
-.buildpath
-.project
-.settings
-.idea
-.DS_Store
-vendor/
-# Don't include the forum module, as this will be installed with composer
-forum
-```
+	```assets/*
+	.env
+	tools/phing-metadata
+	silverstripe-cache
+	.buildpath
+	.project
+	.settings
+	.idea
+	.DS_Store
+	vendor/
+	# Don't include the forum module, as this will be installed with composer
+	forum```
 
 In large projects it can get difficult to manage your [.gitignore](http://git-scm.com/docs/gitignore) and ensure it contains all composer managed modules and themes.
 

docs/en/00_Getting_Started/03_Environment_Management.md

@@ -1,112 +1,65 @@
 # Environment management
 
-As website developers, we noticed that we had a few problems.  You may have the same problems:
-
-*  On our development laptops, we have a number of sites, but the database connection details are the same for each of
-them.  Why should we have to go through the installation process and re-enter them each time?
-*  Each of those sites needed to be in development mode when we were editing them on our laptops, but in production mode
-when we deploy them to our servers.  Additionally, our production host's database connection details will likely be
-different than our local server.
-
-SilverStripe comes with a solution to this: the `_ss_environment.php` file.  You can put a single `_ss_environment.php`
-file in your "projects" folder on your development box, and it will be used by each of your development sites.
-
-## Setting up your development machine with _ss_environment.php
-
-In this example, we assume that you are managing multiple projects as subfolders of `~/Sites/`, and that you can visit
-these at `http://localhost/`.  For example, you might have a project at `~/Sites/myproject/`, and visit it at
-`http://localhost/myproject/`.
-
-Create a new file, `~/Sites/_ss_environment.php`.  Put the following content in it, editing the values of the
-"SS_DATABASE_..." and "SS_DEFAULT_ADMIN_..." defines as appropriate.
-
-	:::php
-	<?php
-	/* What kind of environment is this: development, test, or live (ie, production)? */
-	define('SS_ENVIRONMENT_TYPE', 'dev/test/live');
-
-	/* Database connection */
-	define('SS_DATABASE_SERVER', 'localhost');
-	define('SS_DATABASE_USERNAME', 'root');
-	define('SS_DATABASE_PASSWORD', '');
-
-	/* Configure a default username and password to access the CMS on all sites in this environment. */
-	define('SS_DEFAULT_ADMIN_USERNAME', 'username');
-	define('SS_DEFAULT_ADMIN_PASSWORD', 'password');
-
-
-Now, edit each of your site's configuration file, usually `mysite/_config.php`.  Delete all mention
-of `$databaseConfig` and `Director::set_dev_servers`, and instead make sure that you file starts like this.
-
-	:::php
-	<?php
-
-	global $project;
-	$project = 'mysite';
-
-	global $database;
-	$database = '(databasename)';
-
-	// Use _ss_environment.php file for configuration
-	require_once("conf/ConfigureFromEnv.php");
-
-
-## How it works
-
-The mechanism by which the `_ss_environment.php` files work is quite simple.  Here's how it works:
-
-*  At the beginning of SilverStripe's execution, the `_ss_environment.php` file is searched for, and if it is found, it's
-included.  SilverStripe looks in all the parent folders of framework up to the server root (using the REAL location of
-the dir - see PHP realpath()):
-*  The `_ss_environment.php` file sets a number of "define()".
-*  "conf/ConfigureFromEnv.php" is included from within your `mysite/_config.php`.  This file has a number of regular
-configuration commands that use those defines as their arguments.  If you are curious, open up
-`framework/conf/ConfigureFromEnv.php` and see for yourself!
-
-### An Example
-
-This is my `_ss_environment.php` file. I have it placed in `/var`, as each of the sites are in a subfolder of `/var`.
-
-	:::php
-	<?php
-	// These four define set the database connection details.
-	define('SS_DATABASE_CLASS', 'MySQLPDODatabase');
-	define('SS_DATABASE_SERVER', 'localhost');
-	define('SS_DATABASE_USERNAME', 'root');
-	define('SS_DATABASE_PASSWORD', '<password>');
-
-	// This sets a prefix, which is prepended to the $database variable. This is
-	// helpful mainly on shared hosts, when every database has a prefix.
-	define('SS_DATABASE_PREFIX', 'simon_');
-
-	// These two lines are a bit complicated. If I'm connecting to the server from
-	// 127.0.0.1 or MyIP and I'm using a browser with a + in the UserAgent, the site
-	// is put in dev mode, otherwise it is put in live mode. Most sites would only
-	// need to put the site in either dev or live mode, thus wont need the IP checks
-	if(isset($_SERVER['REMOTE_ADDR']) && ($_SERVER['REMOTE_ADDR'] == '127.0.0.1' || ($_SERVER['REMOTE_ADDR'] == '<MyIP>' 
-	&& strpos($_SERVER['HTTP_USER_AGENT'], '+') !== false))) 
-		define('SS_ENVIRONMENT_TYPE', 'dev');
-	else 
-		define('SS_ENVIRONMENT_TYPE', 'live');
-
-	// These two defines sets a default login which, when used, will always log
-	// you in as an admin, even creating one if none exist.
-	define('SS_DEFAULT_ADMIN_USERNAME', '<email>');
-	define('SS_DEFAULT_ADMIN_PASSWORD', '<password>');
-
-	// This causes errors to be written to the BASE_PATH/silverstripe.log file.
-	// Path must be relative to BASE_PATH
-	define('SS_ERROR_LOG', 'silverstripe.log');
-
-	// This is used by sake to know which directory points to which URL
-	global $_FILE_TO_URL_MAPPING;
-	$_FILE_TO_URL_MAPPING['/var/www'] = 'http://simon.geek.nz';
-
-## Available Constants
+As part of website development and hosting it is natural for our sites to be hosted on several different environments.
+These can be our laptops for local development, a testing server for customers to test changes on, or a production 
+server.
+
+For each of these environments we may require slightly different configurations for our servers. This could be our debug
+level, caching backends, or - of course - sensitive information such as database credentials.
+
+To solve this problem of setting variables per environment we use environment variables with the help of the 
+[PHPDotEnv](https://github.com/vlucas/phpdotenv) library by Vance Lucas.
+
+## Security considerations
+
+Sensitive credentials should not be stored in a VCS or project code and should only be stored on the environment in 
+question. When using live environments the use of `.env` files is discouraged and instead one should use "first class"
+environment variables.
+
+If you do use a `.env` file on your servers, you must ensure that external access to `.env` files is blocked by the
+webserver.
+
+## Managing environment variables with `.env` files
+
+By default the `.env` must be placed in your project root (ie: same folder as you `composer.json`) or the parent
+directory. If this file exists, it will be automatically loaded by the framework and the environment variables will be
+set. An example `.env` file is included in the default installer named`.env.example`.
+
+## Managing environment variables with Apache
+
+You can set "real" environment variables using Apache. Please 
+[see the Apache docs for more information](https://httpd.apache.org/docs/current/env.html)
+
+## How to access the environment variables
+
+Accessing the environment varaibles is easy and can be done using the `getenv` method or in the `$_ENV` and `$_SERVER`
+super-globals:
+
+```php
+getenv('SS_DATABASE_CLASS');
+$_ENV['SS_DATABASE_CLASS'];
+$_SERVER['SS_DATABASE_CLASS'];
+```
+
+## Including an extra `.env` file
+
+Sometimes it may be useful to include an extra `.env` file - on a shared local development environment where all
+database credentials could be the same. To do this, you can add this snippet to your `mysite/_config.php` file:
+
+```php
+try {
+	(new \Dotenv\Dotenv('/path/to/env/'))->load();
+} catch (\Dotenv\Exception\InvalidPathException $e) {
+	// no file found
+}
+```
+
+## Core environment variables
+
+SilverStripe core environment variables are listed here, though you're free to define any you need for your application.
 
 | Name  | Description |
 | ----  | ----------- |
-| `TEMP_FOLDER` | Absolute file path to store temporary files such as cached templates or the class manifest. Needs to be writeable by the webserver user. Defaults to *silverstripe-cache* in the webroot, and falls back to *sys_get_temp_dir()*. See *getTempFolder()* in *framework/core/TempPath.php*.|
 | `SS_DATABASE_CLASS` | The database class to use, MySQLPDODatabase, MySQLDatabase, MSSQLDatabase, etc. defaults to MySQLDatabase.|
 | `SS_DATABASE_SERVER`| The database server to use, defaulting to localhost.|
 | `SS_DATABASE_USERNAME`| The database username (mandatory).|
@@ -125,3 +78,12 @@ This is my `_ss_environment.php` file. I have it placed in `/var`, as each of th
 | `SS_SEND_ALL_EMAILS_TO`| If you define this constant, all emails will be redirected to this address.|
 | `SS_SEND_ALL_EMAILS_FROM`| If you define this constant, all emails will be sent from this address.|
 | `SS_ERROR_LOG` | Relative path to the log file. |
+| `SS_PROTECTED_ASSETS_PATH` | Path to secured assets - defaults to ASSET_PATH/.protected |
+| `SS_DATABASE_MEMORY` | Used for SQLite3 DBs |
+| `SS_TRUSTED_PROXY_PROTOCOL_HEADER` | Used to define the proxy header to be used to determine HTTPS status |
+| `SS_TRUSTED_PROXY_IP_HEADER` | Used to define the proxy header to be used to determine request IPs |
+| `SS_TRUSTED_PROXY_HOST_HEADER` | Used to define the proxy header to be used to determine the requested host name |
+| `SS_TRUSTED_PROXY_IPS` | IP address or CIDR range to trust proxy headers from |
+| `SS_ALLOWED_HOSTS` | A comma deliminated list of hostnames the site is allowed to respond to |
+| `SS_MANIFESTCACHE` | The manifest cache to use (defaults to file based caching) |
+| `SS_IGNORE_DOT_ENV` | If set the .env file will be ignored. This is good for live to mitigate any performance implications of loading the .env file |

docs/en/02_Developer_Guides/04_Configuration/03_Environment_Variables.md

@@ -4,11 +4,10 @@ summary: Site configuration variables such as database connection details, envir
 # Environment Variables
 
 Environment specific variables like database connection details, API keys and other server configuration should be kept 
-outside the application code in a separate `_ss_environment.php` file. This file is stored outside the web root and 
-version control for security reasons. 
+outside the application code in a separate `.env` file. This file is stored in the web root and 
+kept out of version control for security reasons.
 
-For more information on the environment file, see the [Environment Management](../../getting_started/environment_management/) 
-documentation.
+For more information see our docs on [Environment Management](../../getting_started/environment_management/).
 
 Data which isn't sensitive that can be in version control but is mostly static such as constants is best suited to be 
-included through the [Configuration API](configuration) based on the standard environment types (dev / test / live).
+included through the [Configuration API](configuration) based on the standard environment types (dev / test / live).

docs/en/02_Developer_Guides/07_Debugging/00_Environment_Types.md

@@ -13,10 +13,9 @@ The definition of setting an environment type in a `mysite/_config/app.yml` look
 	SilverStripe\Control\Director:
 	  environment_type: 'dev'
 
-The definition of setting an environment type in a `_ss_environment.php` file looks like
+The definition of setting an environment type in a `.env` file looks like
 
-	:::php
-	define('SS_ENVIRONMENT_TYPE', 'dev');
+	SS_ENVIRONMENT_TYPE="dev"
 
 The three environment types you can set are `dev`, `test` and `live`.
 

docs/en/02_Developer_Guides/09_Security/03_Authentication.md

@@ -37,13 +37,12 @@ When a new SilverStripe site is created for the first time, it may be necessary
 CMS access for the first time. SilverStripe provides a default admin configuration system, which allows a username
 and password to be configured for a single special user outside of the normal membership system.
 
-It is advisable to configure this user in your `_ss_environment.php` file outside of the web root, as below:
+It is advisable to configure this user in your `.env` file inside of the web root, as below:
 
-	:::php
-	// Configure a default username and password to access the CMS on all sites in this environment.
-	define('SS_DEFAULT_ADMIN_USERNAME', 'admin');
-	define('SS_DEFAULT_ADMIN_PASSWORD', 'password');
+	# Configure a default username and password to access the CMS on all sites in this environment.
+	SS_DEFAULT_ADMIN_USERNAME="admin"
+	SS_DEFAULT_ADMIN_PASSWORD="password"
 
 When a user logs in with these credentials, then a [api:Member] with the Email 'admin' will be generated in
 the database, but without any password information. This means that the password can be reset or changed by simply
-updating the `_ss_environment.php` file.
+updating the `.env` file.

docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md

@@ -537,11 +537,10 @@ as well as the login form.
 
 To prevent a forged hostname appearing being used by the application, SilverStripe
 allows the configure of a whitelist of hosts that are allowed to access the system. By defining
-this whitelist in your _ss_environment.php file, any request presenting a `Host` header that is
+this whitelist in your `.env` file, any request presenting a `Host` header that is
 _not_ in this list will be blocked with a HTTP 400 error:
 
-	:::php
-	define('SS_ALLOWED_HOSTS', 'www.mysite.com,mysite.com,subdomain.mysite.com');
+	SS_ALLOWED_HOSTS="www.mysite.com,mysite.com,subdomain.mysite.com"
 
 Please note that if this configuration is defined, you _must_ include _all_ subdomains (eg www.)
 that will be accessing the site.
@@ -556,37 +555,35 @@ mechanisms, as rewritten urls could persist between requests in order to misdire
 into visiting external sites.
 
 In order to prevent this kind of attack, it's necessary to whitelist trusted proxy
-server IPs using the SS_TRUSTED_PROXY_IPS define in your _ss_environment.php.
-
+server IPs using the SS_TRUSTED_PROXY_IPS define in your `.env`.
 
-	:::php
-	define('SS_TRUSTED_PROXY_IPS', '127.0.0.1,192.168.0.1');
-	define('SS_TRUSTED_PROXY_HOST_HEADER', 'HTTP_X_FORWARDED_HOST');
-	define('SS_TRUSTED_PROXY_IP_HEADER', 'HTTP_X_FORWARDED_FOR');
-	define('SS_TRUSTED_PROXY_PROTOCOL_HEADER', 'HTTP_X_FORWARDED_PROTOCOL');
+	SS_TRUSTED_PROXY_IPS="127.0.0.1,192.168.0.1"
+	SS_TRUSTED_PROXY_HOST_HEADER="HTTP_X_FORWARDED_HOST"
+	SS_TRUSTED_PROXY_IP_HEADER="HTTP_X_FORWARDED_FOR"
+	SS_TRUSTED_PROXY_PROTOCOL_HEADER="HTTP_X_FORWARDED_PROTOCOL"
 
 At the same time, you'll also need to define which headers you trust from these proxy IPs. Since there are multiple ways through which proxies can pass through HTTP information on the original hostname, IP and protocol, these values need to be adjusted for your specific proxy. The header names match their equivalent `$_SERVER` values.
 
 If there is no proxy server, 'none' can be used to distrust all clients.
 If only trusted servers will make requests then you can use '*' to trust all clients.
 Otherwise a comma separated list of individual IP addresses should be declared.
 
-This behaviour is enabled whenever SS_TRUSTED_PROXY_IPS is defined, or if the
+This behaviour is enabled whenever `SS_TRUSTED_PROXY_IPS` is defined, or if the
 `BlockUntrustedIPs` environment variable is declared. It is advisable to include the
 following in your .htaccess to ensure this behaviour is activated.
 
 
 	<IfModule mod_env.c>
 		# Ensure that X-Forwarded-Host is only allowed to determine the request
-		# hostname for servers ips defined by SS_TRUSTED_PROXY_IPS in your _ss_environment.php
+		# hostname for servers ips defined by SS_TRUSTED_PROXY_IPS in your .env
 		# Note that in a future release this setting will be always on.
 		SetEnv BlockUntrustedIPs true
 	</IfModule>
 
 
 In a future release this behaviour will be changed to be on by default, and this environment
 variable will be no longer necessary, thus it will be necessary to always set
-SS_TRUSTED_PROXY_IPS if using a proxy.
+`SS_TRUSTED_PROXY_IPS` if using a proxy.
 
 ##  Related
 

docs/en/02_Developer_Guides/14_Files/03_File_Security.md

@@ -232,11 +232,10 @@ In order to better ensure these files are protected, it's recommended to move th
 root altogether.
 
 For instance, given your web root is in the folder `/sites/mysite/www`, you can tell the asset store
-to put protected files into `/sites/mysite/protected` with the below `_ss_environment.php` setting:
+to put protected files into `/sites/mysite/protected` with the below `.env` setting:
 
 
-    :::php
-    define('SS_PROTECTED_ASSETS_PATH', '/sites/mysite/protected');
+    SS_PROTECTED_ASSETS_PATH="/sites/mysite/protected"
 
 
 ### Configuring: File types