README

Settings model for the SalesRender plugin ecosystem. Provides per-plugin-instance settings storage based on plugin-component-db and plugin-component-form. Each plugin instance has exactly one Settings record (singleton per plugin) that holds serialized form data (FormData). Includes an integrity guard to verify that settings are properly filled before allowing critical operations.

Installation

composer require salesrender/plugin-component-settings

Requirements

Key classes

Settings

The main model class. Declared as final -- it is not intended for subclassing.

Namespace: SalesRender\Plugin\Components\Settings

Extends: SalesRender\Plugin\Components\Db\Model

Implements: SalesRender\Plugin\Components\Db\SinglePluginModelInterface

Inherited from Model: save(), delete(), getId(), findById(), findByCondition(), addOnSaveHandler(), removeOnSaveHandler(), tableName(), freeUpMemory().

IntegritySettingsException

Thrown by guardIntegrity() when settings validation fails.

Namespace: SalesRender\Plugin\Components\Settings\Exceptions

Extends: \Exception

• HTTP status code: 424 (Failed Dependency)
• Default message: "Settings data empty or incomplete"

FormData

Provided by salesrender/plugin-component-form. Extends Adbar\Dot -- a dot-notation array accessor. Used to store and retrieve individual setting values.

Namespace: SalesRender\Plugin\Components\Form

Key methods (from Adbar\Dot):

• get(string $key, $default = null) -- get a value by dot-notation key
• set(string $key, $value) -- set a value
• has(string $key): bool -- check if a key exists
• toArray(): array -- convert to plain array

Usage

1. Configure the settings form in bootstrap.php

Every plugin must register a settings form during bootstrap. The form defines the fields that appear on the plugin settings page.

From plugin-logistic-cdek:

use SalesRender\Plugin\Components\Settings\Settings;
use SalesRender\Plugin\Instance\Logistic\Settings\SettingsForm;

// Using a callable for lazy loading (recommended)
Settings::setForm(fn() => new SettingsForm());

From plugin-pbx-example:

use SalesRender\Plugin\Components\Settings\Settings;
use SalesRender\Plugin\Instance\Pbx\Forms\SettingsForm;

Settings::setForm(fn() => new SettingsForm());

2. Define a SettingsForm class

The form class extends Form from plugin-component-form and defines the field groups and their validation.

From plugin-logistic-example:

use SalesRender\Plugin\Components\Form\FieldDefinitions\PasswordDefinition;
use SalesRender\Plugin\Components\Form\FieldDefinitions\StringDefinition;
use SalesRender\Plugin\Components\Form\FieldGroup;
use SalesRender\Plugin\Components\Form\Form;
use SalesRender\Plugin\Components\Translations\Translator;

class SettingsForm extends Form
{
    public function __construct()
    {
        parent::__construct(
            Translator::get('settings', 'Settings'),
            null,
            [
                'main' => new FieldGroup(
                    Translator::get('settings', 'Main settings'),
                    null,
                    [
                        'login' => new StringDefinition(
                            Translator::get('settings', 'Login'),
                            null,
                            function () { return []; }
                        ),
                        'password' => new PasswordDefinition(
                            Translator::get('settings', 'Password'),
                            null,
                            function () { return []; }
                        ),
                    ]
                ),
            ],
            Translator::get('settings', 'Save'),
        );
    }
}

3. Read settings values in plugin code

The most common pattern is Settings::find()->getData(), then access individual values with dot notation.

From plugin-logistic-cdek:

use SalesRender\Plugin\Components\Settings\Settings;

$settings = Settings::find()->getData();
$login = $settings->get('main.login');
$password = $settings->get('main.password');

From plugin-chat-eskiz:

use SalesRender\Plugin\Components\Settings\Settings;

$settings = Settings::find()->getData();
$token = $settings->get('main.token');

4. Guard integrity before critical operations

Use guardIntegrity() to ensure settings are valid before performing operations that depend on them. If settings are not filled, an IntegritySettingsException is thrown with HTTP code 424.

From plugin-macros-example:

use SalesRender\Plugin\Components\Settings\Settings;

class ExampleHandler implements BatchHandlerInterface
{
    public function __invoke(Process $process, Batch $batch)
    {
        Settings::guardIntegrity();
        $fields = Settings::find()->getData()->get('group_1.fields');
        // proceed with processing...
    }
}

From plugin-logistic-example (inside form value provider):

use SalesRender\Plugin\Components\Settings\Settings;

$values = new CallableValues(function () {
    Settings::guardIntegrity();
    $data = Settings::find()->getData();
    $senders = [];
    for ($i = 1; $i <= 3; $i++) {
        if ($data->get("sender_{$i}.use", false)) {
            $senders[$i] = [
                'title' => $data->get("sender_{$i}.name"),
                'group' => 'Sender',
            ];
        }
    }
    return $senders;
});

5. Register save handlers

Use addOnSaveHandler() (inherited from Model) to execute logic whenever settings are saved. This is useful for triggering side effects like syncing configuration to external services.

From plugin-pbx-example:

use SalesRender\Plugin\Components\Settings\Settings;

Settings::addOnSaveHandler(function (Settings $settings) {
    $builder = new ConfigBuilder($settings);
    $sender = new ConfigSender($builder);
    $sender();
});

From plugin-core-logistic (named handler):

use SalesRender\Plugin\Components\Settings\Settings;

Settings::addOnSaveHandler(function (Settings $settings) {
    if (LogisticHelper::isFulfillment()) {
        $handler = FulfillmentContainer::getBindingHandler();
        $handler($settings)->sync();
    }
}, 'ffSync');

How it works with plugin-core

The plugin-core framework provides built-in HTTP routes for settings management via SettingsHandler:

These routes are registered automatically by the core framework. Plugin developers only need to configure the form via Settings::setForm() in bootstrap.php.

API reference

Database schema

The Settings table has a single data column. The id, companyId, pluginAlias, and pluginId columns are managed automatically by Model and SinglePluginModelInterface.

Data serialization

• On write (beforeWrite): FormData is serialized to JSON via json_encode()
• On read (afterRead): JSON is deserialized back to FormData via new FormData(json_decode($data, true))

Singleton behavior

Settings implements SinglePluginModelInterface. This means:

• There is exactly one Settings record per plugin instance (identified by pluginId)
• Settings::find() returns the record for the current plugin context, or a new empty Settings if none exists
• The id field is automatically set to Connector::getReference()->getId()

Dependencies

See also

• salesrender/plugin-component-db -- database layer (Model, Connector, SinglePluginModelInterface)
• salesrender/plugin-component-form -- form definitions and FormData
• salesrender/plugin-core -- core framework with SettingsHandler routes