← Erste Schritte · Zurück zur README · Eager Loading →

Mit Einstellungen arbeiten

Der gleiche Service verwaltet Standardwerte und Modellwerte. Der Einstiegspunkt bestimmt, welcher Bereich gelesen oder geändert wird:

Einstiegspunkt	Bereich
(new User)->defaultSettings()	Gemeinsame Standardwerte für gespeicherte User-Modelle
$user->settings()	Effektive Einstellungen eines gespeicherten Benutzers

Gemeinsame Standardwerte

Standardwerte gelten für alle gespeicherten Modelle mit derselben Eloquent-Morph-Klasse:

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

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

Standardwerte werden über denselben Service gelesen oder entfernt:

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

$defaults->forget('timezone');

Standardwerte sind für jede Modellklasse unabhängig.

Modellspezifische Überschreibungen

set() erstellt eine Einstellung oder ersetzt ihren bestehenden Wert:

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

Nur die Einstellung dieses Modells wird geändert. Andere Modelle verwenden weiterhin ihre eigene Überschreibung oder den gemeinsamen Standardwert.

get(), has() und all() lösen Werte mit derselben Priorität auf:

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

all() gibt eine Illuminate\Support\Collection zurück, die nach Einstellungsschlüsseln indiziert ist.

get() akzeptiert nur den Schlüssel. Die Methode gibt zuerst die Modellüberschreibung, dann den persistierten Klassenstandard und anschließend null zurück. Sie akzeptiert keinen vom Aufrufer angegebenen Ersatzwert. has() unterscheidet einen fehlenden Schlüssel von einem gespeicherten JSON-null:

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

Eine Überschreibung ersetzt beispielsweise nur den passenden Standardwert:

(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',
]);

Wert entfernen

Das Entfernen einer Modellüberschreibung macht den Standardwert wieder sichtbar:

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

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

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

Rufe forget() über defaultSettings() auf, um den Standardwert selbst zu entfernen:

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

Der Aufruf von forget() für einen fehlenden Schlüssel hat keine Auswirkung.

Gebündelte Änderungen

Verwende setMany() und forgetMany(), wenn in einem Bereich mehrere Änderungen nötig sind:

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

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

Beide Methoden akzeptieren jedes Iterable. setMany() normalisiert jeden Schlüssel vor dem Schreiben. Werden mehrere Eingabeschlüssel auf denselben gespeicherten Schlüssel normalisiert, gewinnt der letzte Wert. Jeder Wert wird gespeichert; nur forget() und forgetMany() löschen Zeilen.

Ein nicht leerer setMany()-Batch verwendet ein einziges datenbankeigenes Upsert innerhalb einer Transaktion. forgetMany() verwendet einen Löschvorgang für alle angegebenen Schlüssel. Die Anzahl der Abfragen ist durch den Operationstyp begrenzt und hängt nicht von der Anzahl der Schlüssel ab.

Verwende purge(), um den gesamten aktuellen Bereich zu entfernen:

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

Bei settings() löscht purge() nur die Überschreibungen dieses Besitzers und macht persistierte Standardwerte wieder sichtbar. Bei defaultSettings() löscht die Methode die Standardwerte dieser Modellklasse, ohne Modellüberschreibungen zu löschen. Alle drei gebündelten Methoden geben void zurück.

JSON-Werte

set() und setMany() speichern exakte JSON-Werte:

Wert	Ergebnis
null	Gespeichert
'' oder eine Zeichenfolge nur aus Leerzeichen	Gespeichert
[]	Gespeichert
0	Gespeichert
false	Gespeichert
'0'	Gespeichert

Ein gespeichertes null gilt als vorhandener Wert. has($key) gibt true und get($key) gibt null zurück. Eine Modellüberschreibung mit null verdeckt außerdem einen gefüllten Klassenstandard, bis die Überschreibung mit forget() entfernt wird.

Einstellungsschlüssel

Schlüssel können Zeichenfolgen, Ganzzahlen oder PHP-Enums sein, die UnitEnum implementieren:

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

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

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

Laravel speichert ein Backed Enum mit seinem zugrunde liegenden Wert und ein Pure Unit Enum mit seinem Case-Namen. Verwende beim Lesen, Ersetzen oder Entfernen denselben Schlüssel oder Enum-Case.

Leere Schlüssel und Schlüssel, die nur aus Leerzeichen bestehen, lösen DragonCode\LaravelModelSettings\Exceptions\InvalidSettingKey aus. Die Validierung erfolgt nach der Normalisierung von Ganzzahlen und Enums in die gespeicherte Zeichenfolge. Die Exception enthält weder den abgelehnten Schlüssel noch den Payload.

Punkte sind literale Zeichen. Der Schlüssel mail.from.address ist ein einzelner undurchsichtiger Einstellungsschlüssel und bezeichnet nie einen verschachtelten Pfad:

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

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

Modell-IDs

Ganzzahlige, Zeichenfolgen-, UUID- und ULID-Primärschlüssel werden unterstützt.

Modellspezifische Änderungen benötigen einen gespeicherten Besitzer mit einem Schlüssel ungleich null. Für ein ungespeichertes Modell gibt get() null, has() gibt false und all() eine leere Collection zurück, ohne Modellüberschreibungen abzufragen. Seine Methoden set(), setMany(), forget(), forgetMany() und purge() lösen vor einer Speicherabfrage oder dem Durchlaufen des Iterables eine InvalidSettingsOwnerException aus.

Gespeicherte Modelle mit der Ganzzahl-ID 0 oder der Zeichenfolge '0' unterstützen dieselben Lese- und Änderungsvorgänge wie jeder andere gespeicherte Besitzer. Der Bereichsdiskriminator trennt ihre Überschreibungen von Klassenstandards, obwohl beide Zeilen item_id = '0' behalten. Andere Zeichenfolgenschlüssel, einschließlich '00', bleiben gültig.

Einstellungen werden unter der aktuellen Morph-Klasse des Modells gespeichert. Wird ein Morph-Map- Alias nach dem Schreiben von Einstellungen eingeführt oder geändert, müssen vorhandene item_type- Werte aktualisiert werden.

Siehe auch

• Eager Loading — eine Einstellungsabfrage pro Modell vermeiden.
• Payload-Casts — Domänenobjekte statt dekodiertem JSON zurückgeben.
• API-Referenz — Methodensignaturen und Rückgabewerte prüfen.