Перайсці да асноўнага змесціва

← Пачатак працы · Вярнуцца да README · Папярэдняя загрузка →

Праца з наладамі

Адзін сэрвіс працуе і са значэннямі па змаўчанні, і са значэннямі мадэляў. Пункт уваходу вызначае, якая вобласць чытаецца або змяняецца:

Пункт уваходуВобласць
(new User)->defaultSettings()Значэнні па змаўчанні для ўсіх захаваных мадэляў User
$user->settings()Выніковыя налады аднаго захаванага карыстальніка

Агульныя значэнні па змаўчанні​

Значэнні па змаўчанні прымяняюцца да ўсіх захаваных мадэляў з аднолькавым morph-класам Eloquent:

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

$defaults->set('timezone', 'UTC');
$defaults->set('notifications', ['email' => true]);

Чытайце або выдаляйце значэнні па змаўчанні праз той жа сэрвіс:

$timezone = $defaults->get('timezone');
$all = $defaults->all();

$defaults->forget('timezone');

Для кожнага класа мадэлі значэнні па змаўчанні незалежныя.

Перавызначэнні для мадэляў​

set() стварае наладу або замяняе яе бягучае значэнне:

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

Змяняецца толькі налада гэтай мадэлі. Іншыя мадэлі працягваюць выкарыстоўваць уласнае перавызначэнне або агульнае значэнне па змаўчанні.

get(), has() і all() выбіраюць значэнні з аднолькавым прыярытэтам:

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

all() вяртае Illuminate\Support\Collection з ключамі па назвах налад.

get() прымае толькі ключ. Спачатку ён вяртае перавызначэнне мадэлі, затым захаванае значэнне класа па змаўчанні, а потым null. Метад не прымае рэзервовае значэнне ад выклікальніка. has() адрознівае адсутны ключ ад захаванага JSON null:

if ($user->settings()->has('timezone')) {
    $timezone = $user->settings()->get('timezone');
}

Напрыклад, адно перавызначэнне замяняе толькі адпаведнае значэнне па змаўчанні:

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

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

assert($user->settings()->all()->sortKeys()->all() === [
    'locale' => 'en',
    'timezone' => 'Europe/Paris',
]);

Выдаленне значэння​

Пасля выдалення перавызначэння мадэлі зноў выкарыстоўваецца значэнне па змаўчанні:

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

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

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

Каб выдаліць само значэнне па змаўчанні, выклічце forget() праз defaultSettings():

(new User)->defaultSettings()->forget('timezone');

Выклік forget() для адсутнага ключа нічога не змяняе.

Групавыя змяненні​

Выкарыстоўвайце setMany() і forgetMany(), калі ў адной вобласці трэба змяніць некалькі ключоў:

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

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

Абодва метады прымаюць любы iterable. Перад запісам setMany() нармалізуе кожны ключ. Калі некалькі ўваходных ключоў пераўтвараюцца ў адзін захаваны ключ, выкарыстоўваецца апошняе значэнне. Усе значэнні захоўваюцца; радкі выдаляюць толькі forget() і forgetMany().

Непусты пакет setMany() выконвае адзін натыўны upsert у транзакцыі. forgetMany() выдаляе ўсе пералічаныя ключы адным запытам. Колькасць запытаў абмежаваная тыпам аперацыі і не залежыць ад колькасці ключоў.

Выкарыстоўвайце purge(), каб цалкам ачысціць бягучую вобласць:

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

Для settings() метад purge() выдаляе толькі перавызначэнні гэтага ўладальніка, пасля чаго зноў бачныя захаваныя значэнні па змаўчанні. Для defaultSettings() ён выдаляе значэнні па змаўчанні гэтага класа мадэлі, не закранаючы перавызначэнні мадэляў. Усе тры групавыя метады вяртаюць void.

JSON-значэнні​

set() і setMany() захоўваюць JSON-значэнні без змяненняў:

ЗначэннеВынік
nullЗахоўваецца
'' або радок толькі з прабелаўЗахоўваецца
[]Захоўваецца
0Захоўваецца
falseЗахоўваецца
'0'Захоўваецца

Захаваны null лічыцца наяўным значэннем. has($key) вяртае true, а get($key) — null. Перавызначэнне мадэлі са значэннем null таксама хавае запоўненае значэнне класа па змаўчанні, пакуль перавызначэнне не будзе выдалена праз forget().

Ключы налад​

Ключамі могуць быць радкі, цэлыя лікі або PHP-пералічэнні, якія рэалізуюць UnitEnum:

enum SettingKey: string
{
    case Timezone = 'timezone';
}

$user->settings()->set(SettingKey::Timezone, 'Europe/Paris');

$timezone = $user->settings()->get(SettingKey::Timezone);

Laravel захоўвае backed enum як яго базавае значэнне, а pure unit enum — як назву варыянта. Пры чытанні, замене і выдаленні выкарыстоўвайце той жа ключ або варыянт пералічэння.

Пустыя ключы і ключы толькі з прабелаў выклікаюць DragonCode\LaravelModelSettings\Exceptions\InvalidSettingKey. Праверка выконваецца пасля нармалізацыі цэлых лікаў і пералічэнняў у радок для захоўвання. Выключэнне не змяшчае адхілены ключ або даныя налады.

Кропкі лічацца звычайнымі сімваламі. Ключ mail.from.address — гэта адзін непразрысты ключ налады, а не ўкладзены шлях:

$user->settings()->set('mail.from.address', '[email protected]');

$address = $user->settings()->get('mail.from.address');

Ідэнтыфікатары мадэляў​

Падтрымліваюцца цэлалікавыя, радковыя, UUID- і ULID-першасныя ключы.

Для змянення налад мадэлі патрэбны захаваны ўладальнік з ключом, які не роўны null. Для незахаванай мадэлі get() вяртае null, has() — false, а all() — пустую калекцыю без запыту перавызначэнняў. Яе set(), setMany(), forget(), forgetMany() і purge() выклікаюць InvalidSettingsOwnerException да выканання запыту да сховішча або чытання iterable.

Захаваныя мадэлі з цэлалікавым ідэнтыфікатарам 0 або радковым '0' падтрымліваюць тыя ж аперацыі чытання і змянення, што і любы іншы захаваны ўладальнік. Дыскрымінатар вобласці аддзяляе іх перавызначэнні ад значэнняў класа па змаўчанні, хаця абодва радкі захоўваюць item_id = '0'. Іншыя радковыя ключы, уключаючы '00', застаюцца дапушчальнымі.

Налады захоўваюцца для бягучага morph-класа мадэлі. Калі пасля запісу налад дадаць або змяніць псеўданім у morph map, наяўныя значэнні item_type трэба абнавіць.

Гл. таксама​