Version 5 supported

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');

The Environment::getEnv() method will return false both if there was no value set for a variable or if the variable was explicitly set as false. You can determine whether a variable has been set by calling Environment::hasEnv().

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

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

Environment::getEnv() will return false whether the variable was explicitly set as false or simply wasn't set at all. You can use Environment::hasEnv() to check whether an environment variable was set or not.

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);

Note that because _config.php is processed after YAML configuration, variables set in these extra .env files cannot be used inside YAML config.

Core environment variables

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

NameDescription
SS_DATABASE_CLASSThe database class to use. Only MySQLDatabase is included by default, but other values are available in optional modules such as PostgreSQLDatabase. Defaults to MySQLDatabase.
SS_DATABASE_SERVERThe database server to use. Defaults to localhost.
SS_DATABASE_USERNAMEThe database username (mandatory).
SS_DATABASE_PASSWORDThe database password (mandatory).
SS_DATABASE_PORTThe database port.
SS_DATABASE_SUFFIXA suffix to add to the database name.
SS_DATABASE_PREFIXA prefix to add to the database name.
SS_DATABASE_NAMEThe database name. If not set, SS_DATABASE_CHOOSE_NAME must be set instead.
SS_DATABASE_CHOOSE_NAMEBoolean/Int. If defined, then the system will choose a default database name for you. The database name will be "SS_" followed by the name of the folder into which you have installed Silverstripe.
If SS_DATABASE_CHOOSE_NAME is an integer greater than one, then an ancestor folder will be used for the database name. This is handy for a site that's hosted from /sites/examplesite/www or /buildbot/allmodules-2.3/build. If it's 2, the parent folder will be chosen; if it's 3 the grandparent, and so on.

Ignored if SS_DATABASE_NAME is set.
SS_DATABASE_SSL_KEYAbsolute path to SSL key file (optional - but if set, SS_DATABASE_SSL_CERT must also be set)
SS_DATABASE_SSL_CERTAbsolute path to SSL certificate file (optional - but if set, SS_DATABASE_SSL_KEY must also be set)
SS_DATABASE_SSL_CAAbsolute path to SSL Certificate Authority bundle file (optional)
SS_DATABASE_SSL_CIPHERCustom SSL cipher for database connections (optional)
SS_DATABASE_TIMEZONESet the database timezone to something other than the system timezone.
SS_DEPRECATION_ENABLEDEnable deprecation notices for this environment. SS_ENVIRONMENT_TYPE must be set to dev for deprecation notices to show. See Deprecations for more information.
SS_DEPRECATION_SHOW_HTTPInclude deprecation warnings in HTTP responses if SS_ENVIRONMENT_TYPE is true. Defaults to false.
SS_DEPRECATION_SHOW_CLIInclude deprecation warnings in CLI responses if SS_ENVIRONMENT_TYPE is true. Defaults to true.
SS_ENVIRONMENT_TYPEThe environment type. Should be one of dev, test, or live. See Environment Types for more information.
SS_DEFAULT_ADMIN_USERNAMEThe username of the default admin. This is a user with administrative privileges.
SS_DEFAULT_ADMIN_PASSWORDThe password of the default admin. This will not be stored in the database.
SS_USE_BASIC_AUTHBaseline protection for requests handled by Silverstripe CMS. Usually requires additional security measures for comprehensive protection. Set this to the name of a permission which users must have to be able to access the site (e.g. "ADMIN"). See Environment Types for caveats.
SS_SEND_ALL_EMAILS_TOIf you define this constant all emails will be redirected to this address, overriding the original address(es).
SS_SEND_ALL_EMAILS_FROMIf you define this constant all emails will be sent from this address, overriding the original address.
SS_ERROR_LOGPath to a file for logging errors, relative to the project root. See Logging and Error Handling for more information about error logging.
SS_PROTECTED_ASSETS_PATHPath to secured assets - defaults to ASSETS_PATH/.protected. See Protected file paths for more information.
SS_DATABASE_MEMORYUsed for SQLite3 database connectors.
SS_TRUSTED_PROXY_IPSIP address or CIDR range to trust proxy headers from. If left blank no proxy headers are trusted. Can be set to 'none' (trust none) or '*' (trust all). See Request hostname forgery for more information.
SS_ALLOWED_HOSTSA comma deliminated list of hostnames the site is allowed to respond to. See Request hostname forgery for more information.
SS_MANIFESTCACHEThe manifest cache to use (defaults to file based caching). Must be a Psr\Cache\CacheItemPoolInterface, Psr\SimpleCache\CacheInterface, or SilverStripe\Core\Cache\CacheFactory class implementation.
SS_IGNORE_DOT_ENVIf set, the .env file will be ignored. This is good for live to mitigate any performance implications of loading the .env file.
SS_BASE_URLThe URL to use when it isn't determinable by other means (for example for CLI commands). Should either start with a protocol (e.g. https://www.example.com) or with a double forward slash (e.g. //www.example.com).
SS_FLUSH_ON_DEPLOYTry to detect deployments through file system modifications and flush on the first request after every deploy. Does not run "dev/build" - only "flush". Possible values are true (check for a framework PHP file modification time), false (no checks, skip deploy detection) or a path to a specific file or folder to be checked. See DeployFlushDiscoverer for more details.

False by default.
SS_TEMP_PATHFile storage used for the default cache adapters in Manifests, Object Caching and Partial Template Caching. Can be an absolute path (with a leading /), or a path relative to the project root. Defaults to creating a sub-directory of PHP's built-in sys_get_temp_dir() or using the silverstripe-cache directory relative to the project root if one is present.