Model Settings

Model settings keep values stored in the database and can be overriden by the user interface in the backend panel.

# Database Settings

Plugins can use database-driven configuration using models for storing settings in the database by extending the System\Models\SettingModel base class. This model can be used directly for creating the backend settings form. You don't need to create a database table and a controller for creating the backend settings forms based on the settings model. An example of a model setting directory structure:

├── plugins
|   └── acme
|       └── demo
|           ├── models
|           |   ├── usersetting  ← Config Directory
|           |   |   └── fields.yaml  ← Form Fields
|           |   └── UserSetting.php  ← Model Class
|           └── Plugin.php

Settings models can be registered to appear on the settings area in the backend panel, but it is not a requirement - you can set and read settings values like any other model.

# Model Class Definition

The settings model classes should extend the System\Models\SettingModel class, and like any other model, should be defined in the models subdirectory of the plugin directory. The model from the next example should be defined in the plugins/acme/demo/models/UserSetting.php file.

namespace Acme\Demo\Models;

class UserSetting extends \System\Models\SettingModel
{
    public $settingsCode = 'acme_demo_settings';

    public $settingsFields = 'fields.yaml';
}

The $settingsCode property is required for settings models. It defines the unique settings key which is used for saving the settings to the database.

The $settingsFields property is required if you are going to build a backend settings form based on the model. The property specifies a name of the YAML file containing the form fields definition. The form fields are described in the form controller article. The YAML file should be placed to the directory with the name matching the model class name in lowercase.

# Writing to a Settings Model

The settings model has the static set method that allows to save individual or multiple values. You can also use the standard model features for setting the model properties and saving the model.

use Acme\Demo\Models\UserSetting;

// Set a single value
UserSetting::set('api_key', 'ABCD');

// Set an array of values
UserSetting::set(['api_key' => 'ABCD']);

// Set object values
$settings = UserSetting::instance();
$settings->api_key = 'ABCD';
$settings->save();

# Reading From a Settings Model

The settings model has the static get method that enables you to load individual properties. Also, when you instantiate a model with the instance method, it loads the properties from the database and you can access them directly.

// Outputs: ABCD
echo UserSetting::instance()->api_key;

// Get a single value
echo UserSetting::get('api_key');

// Get a value and return a default value if it doesn't exist
echo UserSetting::get('is_activated', true);

# Integration with Multisite

Settings models can provide different configuration values for each site defined by multisite configuration. To enable multisite, include the October\Rain\Database\Traits\Multisite trait inside the model and define a $propagatable property, which can specify fields that propagate across all sites.

namespace Acme\Demo\Models;

class UserSetting extends \System\Models\SettingModel
{
    use \October\Rain\Database\Traits\Multisite;

    public $settingsCode = 'acme_demo_settings';

    public $settingsFields = 'fields.yaml';

    protected $propagatable = [];
}