← Перетворення даних · Повернутися до 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()
Є	Є	Перевизначення, включно з null	true	Перевизначення
Є	Немає	Перевизначення, включно з null	true	Перевизначення
Немає	Є	Значення за замовчуванням, включно з null	true	Значення за замовчуванням
Немає	Немає	null	false	Немає запису

Для незбереженої моделі 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 не очищається.

Див. також

• Робота з налаштуваннями — поведінка кожної операції.
• Попереднє завантаження — використання modelSettings без N+1-запитів.
• Перетворення даних — керування значеннями, які повертають get() і all().