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 SilverStripe\Core\Environment class provides a set of APIs and helpers.
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"
If you do use a
.env file on your servers, you must ensure that external access to
.env files is blocked by the
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
Note: The file must be named exactly
.env and not any variation (such as
.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
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
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
use SilverStripe\Core\Environment; Environment::getEnv('SS_DATABASE_CLASS');
Environment::getEnv()method will return
falseboth 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
Individual settings can be assigned via
use SilverStripe\Core\Environment; Environment::setEnv('API_KEY', 'AABBCCDDEEFF012345');
falsewhether the variable was explicitly set as
falseor 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. You can have multiple
environment variables within a single value, though the overall value must start and end with backticks.
SilverStripe\Core\Injector\Injector: MyServiceClass: properties: MyProperty: '`ENV_VAR_ONE`' MultiValueProperty: '`ENV_VAR_ONE`:`ENV_VAR_TWO`' ThisWillNotSubstitute: 'lorem `REGULAR_TEXT` ipsum'
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
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);
_config.phpis processed after yaml configuration, variables set in these extra
.envfiles 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.
|The database class to use. Only |
|The database server to use. Defaults to |
|The database username (mandatory).|
|The database password (mandatory).|
|The database port.|
|A suffix to add to the database name.|
|A prefix to add to the database name.|
|The database name. If not set, |
|Boolean/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.|
|Set the database timezone to something other than the system timezone.|
|Enable deprecation notices for this environment. |
|Include deprecation warnings in HTTP responses if |
|Include deprecation warnings in CLI responses if |
|The environment type. Should be one of |
|The username of the default admin. This is a user with administrative privileges.|
|The password of the default admin. This will not be stored in the database.|
|Baseline protection for requests handled by Silverstripe. 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.|
|If you define this constant all emails will be redirected to this address, overriding the original address(es).|
|If you define this constant all emails will be sent from this address, overriding the original address.|
|Path to a file for logging errors, relative to the project root. See Logging and Error Handling for more information about error logging.|
|Path to secured assets - defaults to |
|Used for SQLite3 database connectors.|
|IP 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.|
|A comma deliminated list of hostnames the site is allowed to respond to. See Request hostname forgery for more information.|
|The manifest cache to use (defaults to file based caching). Must be a |
|If set, the |
|The url to use when it isn't determinable by other means (eg: for CLI commands). Should either start with a protocol (e.g. |
|Try 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 |
False by default.
|File storage used for the default cache adapters in Manifests, Object Caching and Partial Template Caching. Can be an absolute path (with a leading |