PHPackages                             salesrender/plugin-component-settings - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. salesrender/plugin-component-settings

ActiveLibrary

salesrender/plugin-component-settings
=====================================

SalesRender plugin settings model

0.2.15(2y ago)01.0k↓100%1proprietaryPHPPHP >=7.4.0

Since Sep 22Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/SalesRender/plugin-component-settings)[ Packagist](https://packagist.org/packages/salesrender/plugin-component-settings)[ RSS](/packages/salesrender-plugin-component-settings/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (2)Versions (19)Used By (1)

salesrender/plugin-component-settings
=====================================

[](#salesrenderplugin-component-settings)

Settings model for the SalesRender plugin ecosystem. Provides per-plugin-instance settings storage based on [`plugin-component-db`](https://github.com/SalesRender/plugin-component-db) and [`plugin-component-form`](https://github.com/SalesRender/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
------------

[](#installation)

```
composer require salesrender/plugin-component-settings
```

Requirements
------------

[](#requirements)

RequirementVersionPHP>= 7.4.0ext-json\*salesrender/plugin-component-db^0.3.0salesrender/plugin-component-form^0.10.0 | ^0.11.0Key classes
-----------

[](#key-classes)

### `Settings`

[](#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`

MethodSignatureDescription`getData``getData(): FormData`Returns the stored `FormData` instance (dot-notation accessor for form field values)`setData``setData(FormData $data): void`Replaces the stored form data`find``static find(): Settings`Loads the settings for the current plugin instance (by `Connector::getReference()->getId()`). Returns a new empty `Settings` if none exist`getForm``static getForm(array $context = []): Form`Returns the configured settings `Form`. Throws `RuntimeException` if `setForm()` was not called`setForm``static setForm(Form|callable $form): void`Configures the settings form. Accepts a `Form` instance or a callable that returns one (lazy loading)`guardIntegrity``static guardIntegrity(): void`Validates current settings data against the form. Throws `IntegritySettingsException` (HTTP 424) if data is empty or incomplete`schema``static schema(): array`Database schema: single `data` column of type `TEXT`Inherited from `Model`: `save()`, `delete()`, `getId()`, `findById()`, `findByCondition()`, `addOnSaveHandler()`, `removeOnSaveHandler()`, `tableName()`, `freeUpMemory()`.

### `IntegritySettingsException`

[](#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`

[](#formdata)

Provided by [`salesrender/plugin-component-form`](https://github.com/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
-----

[](#usage)

### 1. Configure the settings form in bootstrap.php

[](#1-configure-the-settings-form-in-bootstrapphp)

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`](https://github.com/SalesRender/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

[](#2-define-a-settingsform-class)

The form class extends `Form` from [`plugin-component-form`](https://github.com/SalesRender/plugin-component-form) and defines the field groups and their validation.

From [`plugin-logistic-example`](https://github.com/SalesRender/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

[](#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

[](#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`](https://github.com/SalesRender/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`](https://github.com/SalesRender/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 get("sender_{$i}.use", false)) {
            $senders[$i] = [
                'title' => $data->get("sender_{$i}.name"),
                'group' => 'Sender',
            ];
        }
    }
    return $senders;
});
```

### 5. Register save handlers

[](#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`](https://github.com/SalesRender/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`](https://github.com/SalesRender/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
-----------------------------

[](#how-it-works-with-plugin-core)

The [`plugin-core`](https://github.com/SalesRender/plugin-core) framework provides built-in HTTP routes for settings management via `SettingsHandler`:

RouteMethodDescription`/forms/settings`GETReturns the settings form definition (calls `Settings::getForm()`)`/data/settings`GETReturns the current settings data (calls `Settings::find()->getData()`)`/data/settings`PUTSaves new settings data (validates against the form, then calls `setData()` + `save()`)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
-------------

[](#api-reference)

### Database schema

[](#database-schema)

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

ColumnTypeDescription`id`(auto)Plugin instance ID (= `Connector::getReference()->getId()`)`companyId`(auto)Company ID from plugin reference`pluginAlias`(auto)Plugin alias from plugin reference`pluginId`(auto)Plugin ID from plugin reference`data``TEXT`JSON-serialized `FormData`### Data serialization

[](#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

[](#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
------------

[](#dependencies)

PackagePurpose[salesrender/plugin-component-db](https://github.com/SalesRender/plugin-component-db)Database ORM: `Model`, `SinglePluginModelInterface`, `Connector`[salesrender/plugin-component-form](https://github.com/SalesRender/plugin-component-form)`Form`, `FormData` (dot-notation data container based on `adbario/php-dot-notation`)See also
--------

[](#see-also)

- [salesrender/plugin-component-db](https://github.com/SalesRender/plugin-component-db) -- database layer (Model, Connector, SinglePluginModelInterface)
- [salesrender/plugin-component-form](https://github.com/SalesRender/plugin-component-form) -- form definitions and FormData
- [salesrender/plugin-core](https://github.com/SalesRender/plugin-core) -- core framework with SettingsHandler routes

###  Health Score

37

—

LowBetter than 82% of packages

Maintenance59

Moderate activity, may be stable

Popularity17

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 75% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~70 days

Recently: every ~12 days

Total

18

Last Release

863d ago

PHP version history (2 changes)0.1.0PHP >=7.2.0

0.2.0PHP >=7.4.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/6140af7bf37913fbad3d596efa1376ede23a55ac226a15b61857f4e58fc26c22?d=identicon)[SalesRender](/maintainers/SalesRender)

---

Top Contributors

[![IvanKalashnikov](https://avatars.githubusercontent.com/u/6877306?v=4)](https://github.com/IvanKalashnikov "IvanKalashnikov (3 commits)")[![XAKEPEHOK](https://avatars.githubusercontent.com/u/3051649?v=4)](https://github.com/XAKEPEHOK "XAKEPEHOK (1 commits)")

### Embed Badge

![Health badge](/badges/salesrender-plugin-component-settings/health.svg)

```
[![Health](https://phpackages.com/badges/salesrender-plugin-component-settings/health.svg)](https://phpackages.com/packages/salesrender-plugin-component-settings)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)