Merge pull request #6645 from open-sausages/pulls/4.0/better-env-guide

Improve upgrading guide for `.env`
This commit is contained in:
Stevie Mayhew 2017-02-24 11:53:17 +13:00 committed by GitHub
commit 81767250ab

View File

@ -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