Environmental Settings

You are viewing documentation for an unreleased version of Craft CMS. Please be aware that some pages, screenshots, and technical reference may still reflect older versions.

Plugin settings that may need to change per-environment, or contain sensitive information, should be implemented as environmental settings.

Environmental settings are settings whose raw values may reference an environment variable or alias, and which get parsed by craft\helpers\App::parseEnv() (opens new window) at runtime.

Here’s an example model with a $secretKey property that may be set to an environment variable, and a getSecretKey() method that is responsible for parsing the value.

use craft\base\Model;
use craft\helpers\App;

class MyModel extends Model
{
    /**
     * @var string the raw secret key (e.g. '$ENV_NAME')
     */
    public $secretKey;

    /**
     * @return string the parsed secret key (e.g. 'XXXXXXXXXXX')
     */
    public function getSecretKey(): string
    {
        return App::parseEnv($this->secretKey);
    }
}

# Validation

If your environmental settings require special validation rules, you can have the validators check the parsed values rather than the raw values using craft\behaviors\EnvAttributeParserBehavior (opens new window).

use craft\base\Model;
use craft\behaviors\EnvAttributeParserBehavior;

class MyModel extends Model
{
    public function behaviors(): array
    {
        return [
            'parser' => [
                'class' => EnvAttributeParserBehavior::class,
                'attributes' => ['secretKey'],
            ],
        ];
    }

    public function rules(): array
    {
        return [
            ['secretKey', 'required'],
            ['secretKey', 'string', 'length' => 50],
        ];
    }

    // ...
}

# Autosuggest Inputs

To guide users when entering your setting’s value in the control panel, give your setting an autosuggest input.

{% import '_includes/forms.twig' as forms %}

{{ forms.autosuggestField({
  label: 'Secret Key'|t('plugin-handle'),
  id: 'secret-key',
  name: 'secretKey',
  value: myModel.secretKey,
  suggestEnvVars: true
}) }}

When suggestEnvVars is set to true, the autosuggest input will call craft\web\twig\variables\Cp::getEnvSuggestions() (opens new window) to get its suggestions, and a tip will show up below the form field advising the user that they can set the value to an environment variable.

If your setting is for a URL or file system path, you should also set suggestAliases to true.




 


{{ forms.autosuggestField({
  // ...
  suggestEnvVars: true,
  suggestAliases: true
}) }}

# Limiting Values

When a setting has a limited number of valid values (and isn’t open-ended), the forms.selectizeField() helper can help users discover appropriate environmental values:











 




{{ forms.selectizeField({
  label: 'Region'|t('my-plugin'),
  instructions: 'The region this resource is located in.'|t('my-plugin'),
  id: 'region',
  name: 'region',
  options: [
    { label: 'Asia Pacific (Hong Kong)', value: 'ap-east-1' },
    { label: 'Europe (Milan)', value: 'eu-south-1' },
    { label: 'US West (N. California)', value: 'us-west-1' },
  ],
  includeEnvVars: true,
  value: model.region,
  errors: model.getErrors('region')
}) }}

For boolean settings, a similar forms.booleanMenuField() is available:

{{ forms.booleanMenuField({
  label: "Use authentication"|t('my-plugin'),
  id: 'useAuthentication',
  name: 'useAuthentication',
  includeEnvVars: true,
  value: model.useAuthentication,
}) }}

Boolean fields only list environment variables that contain values satisfying PHP’s underlying boolean filters (opens new window).