Перейти до основного вмісту

Посібник розробника

Архітектура​

sSettings - це evo-ui + Livewire модуль менеджера.

Основні частини:

  • Seiger\sSettings\sSettingsServiceProvider реєструє переклади, plugin, manager module, routes, views, publish-файли і Livewire компоненти.
  • Seiger\sSettings\Livewire\ModulePanel перемикає Налаштування і Конфігурацію.
  • Seiger\sSettings\Livewire\SettingsPanel рендерить компактний редактор значень.
  • Seiger\sSettings\Livewire\ConfigurePanel рендерить компактний schema builder.
  • Seiger\sSettings\Support\SettingsSchemaRepository читає, нормалізує і безпечно записує схему.
  • Seiger\sSettings\Support\SystemSettingsStore читає і записує системні налаштування sset_*.
  • Seiger\sSettings\Support\FieldCatalog містить каталог типів полів.

Встановлення​

У директорії core Evolution CMS:

php artisan package:installrequire seiger/ssettings "^2.0"
php artisan vendor:publish --provider="Seiger\\sSettings\\sSettingsServiceProvider"

У локальному Extras-середовищі пакет можна підключати як path repository із symlink у demo core.

Файли конфігурації​

Пакетна схема за замовчуванням:

config/sSettingsSettings.php

Записувана схема проєкту:

core/custom/config/seiger/settings/sSettings.php

Якщо проєктної схеми ще немає, sSettings читає пакетну схему.

Форма схеми​

return [
'basicTab' => [
'label' => 'sSettings::global.basicTab',
'fields' => [
[
'name' => 'email',
'label' => 'sSettings::global.email',
'description' => 'sSettings::global.email_description',
'type' => 'text',
],
],
],
];

Відомі перекладені назви при збереженні нормалізуються назад у translation keys. Кастомні назви без перекладу зберігаються як звичайний текст.

Безпечний запис схеми​

SettingsSchemaRepository::save() перевіряє згенерований PHP через token_get_all(..., TOKEN_PARSE) у поточному PHP-процесі, після чого записує тимчасовий файл і замінює цільовий. Згенерований код не виконується; окремий процес не запускається. Збереження працює з PHP-FPM/FastCGI та вимкненим exec(). У разі помилки перевірки або заміни чинний конфіг зберігається.

Після збереження схема синхронізується через SystemSettingsStore::syncSchema(): нові sset_* створюються, а старі sset_*, яких уже немає в схемі, видаляються.

Типи полів​

FieldCatalog підтримує:

  • text
  • textarea
  • textareamini
  • richtext
  • dropdown
  • listbox
  • listboxmultiple
  • radio
  • image
  • file
  • url
  • email
  • number
  • date
  • checkbox
  • checkboxgroup
  • divider

Усі типи, крім divider, зберігають значення. Checkbox нормалізується у 1 або 0, checkbox group і multi-listbox зберігають кілька значень через ||. Опції для dropdown/listbox/radio/checkbox group зберігаються у форматі value==Label||value2==Label 2. Image і File зберігають вибраний шлях як рядок.

Routes і manager module​

Routes завантажуються тільки в manager mode:

GET ssettings
GET ssettings/configure

Manager module зареєстрований як hidden і відкривається через Tools menu. Іконка меню використовує той самий Blade Tabler icon шлях, що й module registration.

evo-ui контракти​

Інтерфейс має залишатися компактним:

  • значення згруповані за табами схеми;
  • у Конфігурації додавання таба зліва, збереження справа;
  • Конфігурація працює як staged editor: модалка поля застосовує локальний draft, а основна кнопка «Зберегти» є єдиною дією persistence для схеми;
  • primary action у модалці поля використовує evo::global.action_apply, неактивна поки draft не змінено, і після застосування робить Configure dirty;
  • порядок табів і полів змінюється drag handles;
  • опції в модалці поля використовують EvoUI data-evo-dnd-option-list і data-evo-dnd-option-row; EvoUI володіє pointer reorder path, а option row, handle та inputs лишаються draggable="false", щоб не було race між modal і native DnD; Alpine слухає EvoUI через evo-ui:dnd-option-changed, без dotted x-on event names;
  • DnD табів і полів Configure слухає EvoUI evo-ui:form-dirty, щоб reorder одразу активував головну кнопку «Зберегти» ще до завершення Livewire redraw;
  • після успішного Configure Save подія ssettings-schema-saved оновлює верхні settings tabs із нормалізованої схеми без reload сторінки;
  • налаштування поля відкриваються у компактному modal;
  • type chips і system key chips маленькі та theme-aware.

Поведінка, специфічна для sSettings, має лишатися в sSettings. У evo-ui варто виносити тільки повторно використовувані manager primitives.

Тести і smoke checks​

find src plugins module tests config lang -name "*.php" -print0 | xargs -0 -n1 php -l
SSETTINGS_DEMO_CORE=/path/to/demo/core php tests/run.php

Release gate перед tag/commit:

composer validate --strict --no-check-publish
composer test
php tests/run.php

Корисні demo-команди:

php artisan package:discover
php artisan view:clear
php artisan route:list --path=ssettings