Download the PHP package timurturdyev/simple-settings without Composer

Simple Settings для Laravel

Лёгкий менеджер настроек для Laravel с поддержкой групп, кэшированием и автоматическим приведением типов.

English

Требования

• PHP 8.2+
• Laravel 12.x

Установка

Опубликуйте конфиг и миграцию:

Запустите миграцию:

Использование

Через Facade

Через сервис-контейнер

Группы

Настройки разделены по группам. Группа по умолчанию — global.

Типы данных

Типы определяются и восстанавливаются автоматически:

Массовая запись

Кэш сбрасывается один раз после записи всех значений.

Обход кэша

Artisan-команды

События

По умолчанию события отключены. Включить можно двумя способами:

Через конфиг (глобально для всего приложения):

Через метод (точечно для конкретного вызова):

withEvents() и withoutEvents() возвращают новый экземпляр — текущий не изменяется.

oldValue и existed в SettingSaved имеют смысл только когда включён активити-лог (см. ниже) — без него старое значение не читается, и в событие летят null / false. Это сделано, чтобы лишний SELECT перед записью выполнялся только когда он реально нужен.

Валидация

Добавьте правила в config/simple-settings.php:

При нарушении правила set() выбрасывает InvalidArgumentException.

Активити-лог (опционально)

Опциональное логирование изменений настроек в отдельную таблицу simple_setting_changes. Без сторонних пакетов — своя модель + listener + миграция (которая накатывается автоматически при php artisan migrate).

Включение: требуются включённые события + включённый аудит:

Когда оба флага включены, перед каждым set() / remove() библиотека читает текущее значение (через кеш — лишних запросов обычно нет) и записывает его в old_payload, новое — в new_payload. Causer берётся из auth()->user() — для CLI/queue остаётся null.

Чтение истории:

Поля записи: group, name, event (created / updated / deleted), old_payload (JSON или null), new_payload, causer_type, causer_id, created_at.

Известные ограничения:

• removeAll() НЕ создаёт записей в активити-логе (он бесшумный по умолчанию). Для аудита очистки группы — слушайте SettingsFlushed событие самостоятельно или удаляйте ключи через remove($key) явно.
• withoutEvents() отключает и события, и активити-лог (логично — лог построен поверх событий). Удобно для bulk-сидов.

Конфигурация

Лимиты значений

Колонка val создаётся как TEXT — на MySQL/MariaDB это 65 535 байт (~64 KB), на PostgreSQL и SQLite ограничения нет. Для типовых настроек этого с большим запасом: список из 200 категорий-объектов влезет, массив из 10 000 коротких строк — тоже. Если упёрлись в лимит — это сигнал, что в одну настройку положили что-то «не то» (каталог товаров, лог, контент). Для таких данных нужна отдельная таблица или другое хранилище, не settings-таблица.

Схема БД

Справочник API

Преимущества

Простой key-value для настроек приложения. Не нужно описывать PHP-класс под каждую группу настроек и не нужна миграция на каждый новый ключ — всё хранится в одной таблице simple_settings, дубликаты исключены составным первичным ключом (group, name). Тип значения (string, int, float, bool, array, null) сохраняется и восстанавливается автоматически. Из зависимостей — только illuminate/database и illuminate/support.

English

Lightweight settings manager for Laravel with group namespacing, caching, and automatic type casting.

Requirements: PHP 8.2+, Laravel 12.x

Install:

Basic usage:

Types (integer, float, boolean, array, null) are detected and restored automatically.

Configuration keys: table_name, cache_key_prefix, events, validation_rules, audit.enabled, audit.table.

Value size limits: the val column is TEXT — 64 KB on MySQL/MariaDB, unlimited on PostgreSQL/SQLite. Typical settings fit with plenty of room (200 catalog-like objects, 10 000 short strings). Hitting the cap usually means the data belongs in its own table, not in settings.

Activity log (optional)

Opt-in change history written to a separate simple_setting_changes table. No external packages — just a model, a listener, and a migration that runs as part of php artisan migrate. Enable both events and audit.enabled in the config; once active, every set() / remove() records old_payload, new_payload, and the causer (auth()->user()).

removeAll() is intentionally silent and dispatches SettingsFlushed instead of per-key entries; listen to it directly if you need to audit group resets.

Artisan commands

setting:get, setting:set, setting:list, setting:clear, setting:delete, plus setting:export {file?} {--group=} and setting:import {file} {--replace} {--group=} for backups and environment-to-environment migration. Round-trip preserves PHP types because the JSON file carries the type column alongside the raw value.

Events

SettingRetrieved, SettingSaved, SettingDeleted, SettingsFlushed. Disabled by default; enable globally via the events config key or per-call via Setting::withEvents(). SettingSaved carries oldValue and existed only when the audit log is on.

Highlights

Plain key-value storage for app settings. No PHP class per settings group, no migration per new key — everything lives in a single simple_settings table, and the composite primary key (group, name) rules out duplicates. Value types (string, int, float, bool, array, null) are stored and restored automatically. The only dependencies are illuminate/database and illuminate/support.

For full documentation see the Russian section above.