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

← Пераўтварэнні даных · Вярнуцца да 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 не ачышчаецца.

Гл. таксама​