Вернуться к README · Начало работы →

Laravel Model Settings

Laravel Model Settings хранит общие настройки по умолчанию и переопределения для отдельных моделей в отдельной таблице базы данных. Пакет подходит для случаев, когда все модели должны начинать с одного значения, но отдельные записи могут его переопределять.

Пакет не добавляет столбцы настроек в родительские таблицы. Настройки не зависят от схемы модели и группируются по morph-классу Eloquent-модели.

Когда пакет подходит

Требование	Поведение пакета
Задать одинаковое начальное значение всем сохранённым моделям	Сохранить одно значение по умолчанию для класса
Изменить значение одной модели	Сохранить переопределение для этой модели
Удалить переопределение	Снова использовать значение по умолчанию для класса
Прочитать настройки многих моделей	Заранее загрузить одну связь со значениями по умолчанию и переопределениями

Порядок выбора значения

При чтении настройки пакет возвращает первое доступное значение:

1. Переопределение для сохранённой модели.
2. Значение по умолчанию для класса этой модели.
3. null.

Источник	timezone
Значение по умолчанию для User	UTC
Переопределение для пользователя 123	Europe/Paris
Итоговое значение для пользователя 123	Europe/Paris
Итоговое значение для другого сохранённого пользователя	UTC

Удаление переопределения снова открывает доступ к значению по умолчанию. Само значение по умолчанию не удаляется.

Основные операции

(new User)->defaultSettings()->set('timezone', 'UTC');

$user->settings()->set('timezone', 'Europe/Paris');

$timezone = $user->settings()->get('timezone');
$settings = $user->settings()->all();
$hasTimezone = $user->settings()->has('timezone');

$user->settings()->setMany([
    'locale' => 'fr',
    'notifications.email' => true,
]);
$user->settings()->forgetMany(['timezone', 'locale']);

get() возвращает одно итоговое значение. all() возвращает Illuminate\Support\Collection, в которой значения по умолчанию объединены с переопределениями. Используйте has(), когда нужно проверить наличие итогового ключа, в том числе при сохранённом JSON null. get() намеренно не принимает резервное значение от вызывающего кода: единственным резервным значением остаётся сохранённое значение класса по умолчанию, а при отсутствии ключа в обеих областях возвращается null.

Для значений по умолчанию и переопределений доступны одинаковые операции: all(), get(), has(), set(), setMany(), forget(), forgetMany() и purge().

Границы специализированного пакета

Laravel Model Settings — специализированный пакет для Eloquent, а не универсальный фреймворк настроек приложения.

Граница	Намеренное поведение
Хранение	Одна таблица базы данных; без Redis и хранения в полях родительской модели
Значения по умолчанию	Служебные строки в той же таблице; без второй таблицы значений по умолчанию
Регистрация	Без реестра репозиториев, типизированных глобальных классов настроек и обнаружения классов
Миграции	Без средства запуска миграций для отдельных ключей настроек
Кэширование	Без обязательного межзапросного кэша; предварительная загрузка переиспользует только загруженную связь

Приложениям с такими требованиями следует реализовать их вне пакета, а не использовать modelSettings или внутренний репозиторий как API расширения.

Границы хранения

Каждая строка определяется четырьмя значениями:

Значение	Смысл
item_type	Morph-класс родительской модели или псевдоним из morph map
item_id	Первичный ключ родителя; для настроек класса по умолчанию сохраняется физическое значение 0
is_default	true для настройки класса по умолчанию, false для переопределения модели
key	Имя настройки

Благодаря этому значения по умолчанию независимы для каждого класса модели. Значение по умолчанию для User никогда не становится значением по умолчанию для Post, даже если оба класса используют один ключ настройки.

Поддерживаемые модели

Пакет поддерживает Eloquent-модели с целочисленными, строковыми, UUID- и ULID-первичными ключами. Сохранённые модели с целочисленным идентификатором 0 или строковым '0' могут хранить переопределения без конфликта со значениями класса по умолчанию. Также можно использовать Laravel morph map.

Настройки отдельных моделей относятся только к сохранённым моделям. Несохранённая модель не наследует значения по умолчанию: get() возвращает null, has() — false, а all() — пустую коллекцию. Вызов set(), setMany(), forget(), forgetMany() или purge() для несохранённого владельца выбрасывает InvalidSettingsOwnerException до выполнения запроса к хранилищу.

Данные настроек хранятся в JSON, включая null, пустые строки, строки из пробелов, пустые массивы, ноль и false. Без настроенного преобразования чтение возвращает точное декодированное значение. Преобразования данных позволяют возвращать объекты приложения.

См. также

• Начало работы — установка пакета и настройка модели.
• Работа с настройками — управление значениями по умолчанию, переопределениями, ключами и значениями.
• Справочник API — все публичные методы и возвращаемые типы.