Перейти к основному содержимому

← Преобразования данных · Вернуться к README · Разработка →

Справочник API

Трейт HasSettings​

МетодВозвращаетНазначение
settings()SettingsServiceДоступ к итоговым настройкам этой модели
defaultSettings()SettingsServiceДоступ к общим значениям по умолчанию для класса модели
modelSettings()Eloquent RelationЗагрузка значений по умолчанию и переопределений как связи

Используйте связь modelSettings только с with(), load() или loadMissing() и как полученное загруженное свойство. Не используйте запрос связи как альтернативный API чтения или CRUD. Читайте и изменяйте значения через два сервиса. Во время выполнения связь представлена пакетным классом SettingsRelation, основанным на связи Laravel MorphMany.

SettingsService​

МетодВозвращаетПоведение
all()CollectionВозвращает значения по умолчанию, объединённые с переопределениями модели
get(int|string|UnitEnum $key)mixedВозвращает переопределение, значение по умолчанию или null
has(int|string|UnitEnum $key)boolСообщает о наличии итогового ключа, включая сохранённый null
set(int|string|UnitEnum $key, mixed $value)voidСоздаёт или заменяет настройку точным JSON-значением
setMany(iterable $values)voidЗаписывает все значения одним ограниченным транзакционным пакетом
forget(int|string|UnitEnum $key)voidУдаляет настройку, если она существует
forgetMany(iterable $keys)voidУдаляет перечисленные ключи из текущей области
purge()voidУдаляет все настройки, сохранённые в текущей области

Методы с ключом принимают backed enum и pure unit enum. Laravel преобразует backed enum в его базовое значение, а pure unit enum — в имя варианта.

У SettingsService нет резервного аргумента для get(). Используйте has($key), чтобы отличить отсутствующий итоговый ключ от сохранённого JSON null.

Матрица выбора значения​

Переопределение моделиЗначение класса по умолчаниюРезультат get()Результат has()Включено в all()
ЕстьЕстьПереопределение, включая nulltrueПереопределение
ЕстьНетПереопределение, включая nulltrueПереопределение
НетЕстьЗначение по умолчанию, включая nulltrueЗначение по умолчанию
НетНетnullfalseНет записи

Для несохранённой модели get() возвращает null, has() — false, а all() — пустую коллекцию. Значения класса по умолчанию наследуются только сохранёнными моделями.

all​

$settings = $user->settings()->all();

$timezone = $settings->get('timezone');

Результат — Illuminate\Support\Collection с ключами по ключам настроек. Для настроек модели переопределения заменяют значения по умолчанию с тем же ключом.

get​

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

Результат содержит итоговое декодированное или преобразованное значение. Если переопределения нет, используется значение по умолчанию. Если нет ни переопределения, ни значения по умолчанию, возвращается null. Сигнатура намеренно не принимает второй резервный аргумент.

has​

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

Метод возвращает true, если существует строка переопределения модели или значения класса по умолчанию. Сохранённый JSON null даёт true, отсутствующий ключ — false. Ленивая и предварительная загрузка используют одинаковый приоритет, а предварительно загруженный путь не выполняет дополнительный запрос настроек.

set​

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

Метод проверяет владельца и нормализованный ключ, затем выполняет update-or-create для типа модели, идентификатора модели, дискриминатора области и ключа. Сохраняется каждое JSON-значение, включая null, пустые строки, строки из пробелов, пустые массивы, ноль и false. После успешной записи загруженная связь modelSettings очищается, чтобы следующее чтение не использовало устаревшие данные.

setMany​

$user->settings()->setMany([
    'timezone' => 'Europe/Paris',
    'locale' => 'fr',
    'obsolete' => null,
]);

Ключи iterable нормализуются так же, как в set(). Если несколько входных ключей преобразуются в одну строку, используется последнее значение. Все значения записываются одним нативным upsert внутри транзакции. Метод проверяет владельца до чтения iterable и один раз очищает modelSettings после успешного выполнения. Для удаления используйте forgetMany().

forget​

$user->settings()->forget('timezone');

Для допустимого владельца метод безопасен, если ключ отсутствует. Удаление переопределения не удаляет общее значение по умолчанию. После удаления загруженная связь очищается.

forgetMany​

$user->settings()->forgetMany(['timezone', 'locale']);

Метод нормализует iterable, удаляет дубликаты и одним запросом удаляет только указанные ключи из текущей области. Отсутствующие ключи ничего не меняют. Метод возвращает void и очищает загруженную связь после успешного вызова, включая пустой iterable.

purge​

$user->settings()->purge();

Для settings() метод удаляет все переопределения сохранённого владельца. Значения класса по умолчанию и переопределения других владельцев не удаляются. Для defaultSettings() удаляются все значения по умолчанию этого класса модели, а переопределения моделей сохраняются. Метод возвращает void и очищает загруженную связь после успеха.

defaultSettings​

Сервис, возвращаемый defaultSettings(), предоставляет те же восемь методов:

$defaults = (new User)->defaultSettings();

$defaults->set('timezone', 'UTC');
$defaults->setMany(['timezone' => 'UTC', 'locale' => 'en']);
$timezone = $defaults->get('timezone');
$hasTimezone = $defaults->has('timezone');
$all = $defaults->all();
$defaults->forget('timezone');
$defaults->forgetMany(['timezone', 'locale']);
$defaults->purge();

Исключения​

DragonCode\LaravelModelSettings\Exceptions\InvalidSettingsOwnerException расширяет PHP-класс DomainException. Любой изменяющий метод через settings() выбрасывает его до запроса к хранилищу для несохранённой модели-владельца, включая несохранённую модель с заранее назначенным ключом.

Эта проверка также выполняется до чтения группового iterable. Изменения через defaultSettings() остаются допустимыми, потому что этот сервис явно выбирает область значений класса по умолчанию. Чтение остаётся однозначным: несохранённый владелец возвращает null или пустую коллекцию без запроса переопределений, а has() возвращает false. Сохранённый владелец с целочисленным ключом 0 или строковым '0' может читать и изменять свои переопределения; is_default отделяет эти строки от значений класса по умолчанию.

DragonCode\LaravelModelSettings\Exceptions\InvalidPayloadCast выбрасывается, если настроенное для модели или ключа преобразование отсутствует, имеет неверный тип, не реализует поддерживаемый контракт или не разрешается контейнером Laravel. Сообщение может содержать класс родительской модели, ключ настройки и класс преобразования, но никогда не содержит данные настройки.

DragonCode\LaravelModelSettings\Exceptions\InvalidSettingKey выбрасывается после нормализации, если ключ пуст или состоит только из пробелов. Сообщение исключения не содержит отклонённый ключ или данные настройки.

DragonCode\LaravelModelSettings\Exceptions\BulkMutationException расширяет PHP-класс RuntimeException. Это исключение оборачивает неожиданные ошибки чтения iterable, сериализации и хранилища в setMany(), forgetMany() и purge(). Его сообщение указывает операцию, класс владельца и область model или default, но не содержит ключи и данные настроек. Исходное исключение доступно через getPrevious().

Существующие исключения пакета InvalidSettingsOwnerException, InvalidPayloadCast и InvalidSettingKey не оборачиваются. При ошибке непустой операции setMany() транзакция откатывает пакет, а существующая загруженная связь modelSettings не очищается.

См. также​