If your Craft project lives across more than one environment (e.g. Development, Staging, and Production), there are going to be things that should be configured differently for each environment.
These aren’t mutually exclusive. Most Craft projects will use both approaches for different things.
Environment variables are values that are set on the server that Craft is running on, which can be loaded with PHP’s getenv() function.
They can be set in multiple ways – for example some hosts provide a UI for defining environment variables – but in general we recommend you set them in the
.env file that comes with new Craft 3 projects.
.env files are special because they don’t get committed to Git like the rest of your project’s files. So it’s a good place to put information that is sensitive or likely to change for each environment.
To set a new environment variable, open up your
.env file and add it like this:
# -- .env -- SITE_URL="http://my-project.test"
See the PHP Dotenv documentation for more info on supported
Whenever you add a new variable to
.env, you should add it to
.env.example as well, probably without a value.
.env.example is the starting point that new environments should base their
.env file on.
# -- .env.example -- SITE_URL=""
// -- config/general.php -- 'siteUrl' => getenv('SITE_URL'),
If there’s a chance that some environments won’t have the environment variable defined, use a ternary operator (
?:) to define a fallback value:
// -- config/general.php -- 'siteUrl' => getenv('SITE_URL') ?: '/',
All of Craft’s config files (the
.php files in your
config/ folder) can optionally define separate config settings for each individual environment.
Take this simple single-environment config:
// -- config/general.php -- return [ 'omitScriptNameInUrls' => true, 'siteUrl' => 'https://example.com', ];
Let’s say you want to give your Development environment a different
siteUrl value. To do that, first make this a multi-environment config by moving all of your config settings into a nested array, with a
// -- config/general.php -- return [ // Global settings '*' => [ 'omitScriptNameInUrls' => true, 'siteUrl' => 'https://example.com', ], ];
Now Craft knows to treat this as a multi-environment config. All that’s left is to override the
siteUrl setting for Development:
// -- config/general.php -- return [ // Global settings '*' => [ 'omitScriptNameInUrls' => true, 'siteUrl' => 'https://my-project.com', ], // Dev environment settings 'dev' => [ 'siteUrl' => 'http://my-project.test', ], ];
The actual environment names you go with are up to you. Craft will look for the key(s) with the same name as the CRAFT_ENVIRONMENT PHP constant, which should be defined by your
By default, new Craft 3 projects will define the CRAFT_ENVIRONMENT constant using an environment variable called
ENVIRONMENT, which is defined in the
// -- web/index.php -- // Load and run Craft define('CRAFT_ENVIRONMENT', getenv('ENVIRONMENT') ?: 'production');
# -- .env -- # The environment Craft is currently running in ('dev', 'staging', 'production', etc.) ENVIRONMENT="dev"
If the CRAFT_ENVIRONMENT constant isn’t defined, Craft will define it for you based on the current server name (e.g.
my-project.test), for backwards compatibility with configs created for Craft 2. We recommend you explicitly define it yourself, though.
'*' array is required to enable Craft’s multi-environment config support, even if it’s blank. Craft checks for it when determining whether a config is multi-environment or not.
Aliases provide a way to define paths and URLs on a per-environment basis.
For example, you might want to define
ASSET_BASE_URL environment variables that store the base path and URL to a
web/assets/ folder, where your asset volumes will live:
# -- .env -- # Path to web/assets/ relative to index.php ASSET_BASE_PATH="./assets" # URL to web/assets/ ASSET_BASE_URL="/assets"
You can pull these environment variables into custom aliases from your
config/general.php file like so:
'aliases' => [ '@assetBasePath' => getenv('ASSET_BASE_PATH'), '@assetBaseUrl' => getenv('ASSET_BASE_URL'), ],
With that in place, you can start referencing your new aliases from your asset volume settings: