Przewodnik developera
Architektura
sSettings jest modułem managera opartym o evo-ui i Livewire.
Główne elementy:
Seiger\sSettings\sSettingsServiceProviderrejestruje tłumaczenia, plugin, manager module, routes, views, pliki publikowane i komponenty Livewire.Seiger\sSettings\Livewire\ModulePanelprzełącza Ustawienia i Konfigurację.Seiger\sSettings\Livewire\SettingsPanelrenderuje kompaktowy edytor wartości.Seiger\sSettings\Livewire\ConfigurePanelrenderuje kompaktowy builder schematu.Seiger\sSettings\Support\SettingsSchemaRepositoryczyta, normalizuje i bezpiecznie zapisuje schemat.Seiger\sSettings\Support\SystemSettingsStoreczyta i zapisuje ustawienia systemowesset_*.Seiger\sSettings\Support\FieldCatalogzawiera katalog typów pól.
Instalacja
W katalogu core Evolution CMS:
php artisan package:installrequire seiger/ssettings "^2.0"
php artisan vendor:publish --provider="Seiger\\sSettings\\sSettingsServiceProvider"
W lokalnym środowisku Extras pakiet może być podłączony jako path repository z symlinkiem do demo core.
Pliki konfiguracji
Domyślny schemat pakietu:
config/sSettingsSettings.php
Zapisywalny schemat projektu:
core/custom/config/seiger/settings/sSettings.php
Jeśli schemat projektu nie istnieje, sSettings używa schematu domyślnego.
Kształt schematu
return [
'basicTab' => [
'label' => 'sSettings::global.basicTab',
'fields' => [
[
'name' => 'email',
'label' => 'sSettings::global.email',
'description' => 'sSettings::global.email_description',
'type' => 'text',
],
],
],
];
Znane przetłumaczone etykiety są przy zapisie normalizowane z powrotem do kluczy tłumaczeń. Własne etykiety bez tłumaczenia są zapisywane jako tekst.
Bezpieczny zapis schematu
SettingsSchemaRepository::save() sprawdza wygenerowany PHP przez
token_get_all(..., TOKEN_PARSE) w bieżącym procesie PHP, a następnie zapisuje
plik tymczasowy i zastępuje plik docelowy. Nie wykonuje wygenerowanego kodu ani
nie uruchamia procesu potomnego, więc działa z PHP-FPM/FastCGI i wyłączonym
exec(). Błąd walidacji lub zastąpienia pozostawia dotychczasową konfigurację.
Po zapisie schemat jest synchronizowany przez
SystemSettingsStore::syncSchema(): nowe sset_* są tworzone, a stare
sset_*, których nie ma już w schemacie, są usuwane.
Typy pól
FieldCatalog obsługuje:
texttextareatextareaminiimagefilecheckboxdivider
Wszystkie typy poza divider zapisują wartości. Checkbox jest normalizowany do
1 albo 0, pozostałe wartości do przyciętego stringa. Image i File zapisują
wybraną ścieżkę jako string.
Routes i manager module
Routes są ładowane tylko w manager mode:
GET ssettings
GET ssettings/configure
Manager module jest zarejestrowany jako hidden i otwierany z Tools menu. Ikona menu używa tej samej ścieżki Blade Tabler icon co rejestracja modułu.
Kontrakty evo-ui
Interfejs powinien pozostać kompaktowy:
- wartości są grupowane według zakładek schematu;
- w Konfiguracji dodawanie zakładki jest po lewej, zapis po prawej;
- Konfiguracja jest staged editor: modal pola stosuje lokalny draft, a glowny przycisk Save jest jedyna akcja persistence dla schematu;
- primary action w modalu pola uzywa
evo::global.action_apply, jest wylaczona gdy draft sie nie zmienil i po apply oznacza Configure jako dirty; - zakładki i pola zmieniają kolejność przez drag handles;
- opcje w modalach pol uzywaja EvoUI
data-evo-dnd-option-listidata-evo-dnd-option-row; EvoUI posiada pointer reorder path, a option row, handle i inputy pozostajadraggable="false", zeby uniknac race miedzy modalem i native DnD; Alpine slucha przezevo-ui:dnd-option-changed, bez dottedx-onevent names dla tej sciezki; - DnD zakladek i pol Configure slucha EvoUI
evo-ui:form-dirty, zeby reorder od razu wlaczal glowny przycisk Save przed zakonczeniem redraw Livewire; - po udanym Configure Save event
ssettings-schema-savedodswieza gorne settings tabs z normalizowanego schematu bez reload strony; - ustawienia pola otwierają się w kompaktowym modalu;
- type chips i system key chips są małe i zgodne z motywem.
Logika specyficzna dla sSettings powinna zostać w sSettings. Do evo-ui należy wynosić tylko wielokrotnego użytku manager primitives.
Testy i 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
Przydatne komendy demo:
php artisan package:discover
php artisan view:clear
php artisan route:list --path=ssettings