Environment management#

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 manage environment variables, as well as other server globals, the Environment class provides a set of APIs and helpers.

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 a file named .env must be placed in your project root (ie: the same folder as your 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.

Note: The file must be named exactly .env and not any variation (such as mysite.env or .env.mysite) or it will not be detected automatically. If you wish to load environment variables from a file with a different name, you will need to do so manually. See the Including an extra .env file section below for more information.

Other ways to manage environment variables#

Silverstripe CMS will respect environment variables provided by the server.

If you are using a docker compose setup, you can set environment variables in your docker-compose.yml file. See the docker compose docs for more information.

You can set environment variables using Apache. Please see the Apache docs for more information.

How to access the environment variables#

Accessing the environment variables should be done via the Environment::getEnv() method.

use SilverStripe\Core\Environment;
Environment::getEnv('SS_DATABASE_CLASS');

Individual settings can be assigned via Environment::setEnv() or Environment::putEnv() methods.

use SilverStripe\Core\Environment;
Environment::setEnv('API_KEY', 'AABBCCDDEEFF012345');

Using environment variables in config#

To use environment variables in .yaml configs you can reference them using backticks. This only works in Injector configuration. See the Injector documentation for details.

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 app/_config.php file:

Note that by default variables cannot be overridden from this file; Existing values will be preferred over values in this file.

use SilverStripe\Core\EnvironmentLoader;
$env = BASE_PATH . '/app/.env';
$loader = new EnvironmentLoader();
$loader->loadFile($env);

Core environment variables#

Silverstripe core environment variables are listed here, though you're free to define any you need for your application.

If you want to configure environment variables for read-only replica databases, then view the Read-only database replicas documentation.