Skip to content

Latest commit

 

History

History
108 lines (81 loc) · 3.55 KB

environments.md

File metadata and controls

108 lines (81 loc) · 3.55 KB
Raw

Environmental Configuration

Some settings should be defined on a per-environment basis. For example, when developing locally, you may want your site’s base URL to be http://my-project.test, but on production it should be https://my-project.com.

Control Panel Settings

Some settings in the Control Panel can be set to environment variables (like the ones defined in your .env file):

  • General Settings
    • System Name
  • Sites
    • Base URL
  • Sections
    • Preview Target URIs
  • Asset Volumes
    • Base URL
    • File System Path (Local)
  • Email
    • System Email Address
    • Sender Name
    • HTML Email Template
    • Username (Gmail and SMTP)
    • Password (Gmail and SMTP)
    • Host Name (SMTP)
    • Port (Port)

To set these settings to an environment variable, type $ followed by the environment variable’s name.

A volume’s Base URL setting

Only the environment variable’s name will be stored in your database or project config, so this is a great way to set setting values that may change per-environment, or contain sensitive information.

::: tip Plugins can add support for environment variables and aliases in their settings as well. See Environmental Settings to learn how. :::

Using Aliases in Control Panel Settings

Some of these settings—the ones that store a URL or a file system path—can also be set to aliases, which is helpful if you just want to store a base URL or path in an environment variable, and append additional segments onto it.

For example, you can define a ROOT_URL environment variable that is set to the root URL of your site:

# -- .env --
ROOT_URL="http://my-project.test"

Then create a @rootUrl alias that references it:

// -- config/general.php --
'aliases' => [
    '@rootUrl' => getenv('ROOT_URL'),
],

Then you could go into your User Photos volume’s settings (for example) and set its Base URL to @rootUrl/images/user-photos.

Config Files

You can set your general config settings, database connection settings, and other PHP config files to environment variables using PHP’s getenv() function:

# -- .env --
CP_TRIGGER="secret-word"
// -- config/general.php --
'cpTrigger' => getenv('CP_TRIGGER') ?: 'admin',

Multi-Environment Configs

Craft’s PHP config files can optionally define separate config settings for each individual environment.

// -- config/general.php --
return [
    // Global settings
    '*' => [
        'omitScriptNameInUrls' => true,
    ],

    // Dev environment settings
    'dev' => [
        'devMode' => true,
    ],

    // Production environment settings
    'production' => [
        'cpTrigger' => 'secret-word',
    ],
];

The '*' key is required here so Craft knows to treat it as a multi-environment key, but the other keys are up to you. Craft will look for the key(s) that match the CRAFT_ENVIRONMENT PHP constant, which should be defined by your web/index.php file. (Your server’s hostname will be used as a fallback.)

By default, new Craft 3 projects will define the CRAFT_ENVIRONMENT constant using an environment variable called ENVIRONMENT, which is defined in the .env file:

# -- .env --
ENVIRONMENT="dev"
// -- web/index.php --
define('CRAFT_ENVIRONMENT', getenv('ENVIRONMENT') ?: 'production');