Settings + Config

You are viewing documentation for an unreleased version of Craft CMS. Please be aware that the material is changing frequently and may be incomplete or inaccurate, and links may point back to older versions.

As mentioned in the base plugin class section, the return type for your createSettingsModel() function has changed.

#Config Files

If you want a user-space config file, add a config/my-plugin-handle.php to the root of your package and it will be published by the CraftCms\Cms\Plugin\Concerns\HasConfig plugin trait, automatically. Config loaded in this way is overlaid on the object returned by createSettingsModel().

#Environmental Config

To support environment variable overrides on your settings class (or any model, for that matter), call Env::config($class, 'MY_PLUGIN_NS_').

Plugin settings that support environment variables or aliases should wrap their validation rules in the special CraftCms\Cms\Validation\Rules\EnvValueRule class to check the parsed values, without replacing those properties on the actual model. You do not need to juggle the submitted values before they’re sent to project config.

#Initialization

Yii’s system was heavily configuration-driven: objects were initialized with a config map that would cascade down through any nested objects. Places you’d use Craft::createObject() can be mostly replaced with app()->make($class, [...]).

#Validation

The new settings model will be compatible for most plugins, but you will need to adopt new validation patterns to drop the adapter:

// Remove:
public function defineRules(): array
{}

// Add...
public function getRules(): array
{
    return array_merge(parent::getRules(), [
        'adminNotificationAddress' => ['required', 'email:rfc'],
    ]);
}

// ...or:
public function rulesClass(): string
{
    return MyPluginSettingsRuleset::class;
}

You may also tag the settings model with the #[Ruleset(MyPluginSettingsRuleset::class)] attribute. For more control over how your settings data is normalized, return your own form request class from getSettingsRequestClass().

See our Guest Entries (opens new window) plugin for an example of these new techniques.