Pripájanie atribútov a metadát

Attributes::for($model)->set() atribút vytvorí, alebo ho aktualizuje na mieste, ak názov už existuje — vlastník má pre každý názov jeden riadok a odpojený názov dostane svoj riadok späť s novou hodnotou aj metadátami:

use RoundlyConsulting\Attributes\Facades\Attributes;

// One attribute — creates it, or updates it in place; returns the Attribute model
Attributes::for($product)->set('color', 'white');
Attributes::for($product)->set('color', 'black'); // same row, new value

// Several at once from a name => value map; attributes you don't name are kept
Attributes::for($product)->setMany([
    'color' => 'white',
    'size'  => 'large',
    'stock' => 12,
]);                                                // Collection<Attribute>

Čo sa deje pri pripojení

• Prísny režim — pri zapnutom režime názov bez globálnej definície aj bez definície v schéme modelu vyhodí UnknownAttributeException.
• Validácia — zaregistrovaný názov sa overí voči svojmu typu a pravidlám (InvalidAttributeValueException).
• Jedinečnosť — jedinečná definícia odmietne hodnotu, ktorú už má iný vlastník (DuplicateAttributeValueException); súbežné zápisy rozsúdi unikátny index.
• Uloženie — hodnota sa uloží v type z definície (inak v type PHP hodnoty); šifrované definície sa uložia ako šifrový text. Bez nových metadát zostanú uložené metadáta zachované.
• História — pri zapnutej histórii sa zaznamená revízia attached alebo updated.
• Udalosť — AttributeAttached sa spustí po commite transakcie zápisu.

setMany() spustí rovnaký postup pre každú položku mapy názov → hodnota, a to celý alebo vôbec: každá hodnota sa overí pred prvým zápisom a zápisy zdieľajú jednu transakciu.

Na modeli

attachAttribute() a attachAttributes() sú skratky na modeli pre set() a setMany() — delegujú na ten istý manager a vracajú model, takže volania môžete reťaziť:

// One attribute — creates it, or updates it in place
$product->attachAttribute('color', 'white');
$product->attachAttribute('color', 'black'); // same row, new value

// Several at once from a name => value map
$product->attachAttributes([
    'color' => 'white',
    'size'  => 'large',
    'stock' => 12,
]);

// Writers return the model, so calls chain
$product->attachAttribute('on_sale', true)->attachAttribute('discount', 0.15);

Metadáta

Každý atribút môže niesť kolekciu metadát — hex kód farby, jednotku, pôvod hodnoty. Odovzdajte ju ako pole alebo Collection pri zápise atribútu, alebo ju neskôr nahraďte cez meta():

use RoundlyConsulting\Attributes\Facades\Attributes;

// Attach with metadata (an array or a Collection)
Attributes::for($product)->set('color', 'white', meta: ['hex' => '#ffffff']);

// setMany() and sync() take a per-name meta map as their last argument
Attributes::for($product)->setMany(['color' => 'white', 'size' => 'L'], meta: ['color' => ['hex' => '#ffffff']]);

$product->getAttachedAttributeMeta('color'); // Collection: ['hex' => '#ffffff']

// A new value without meta keeps the stored meta
Attributes::for($product)->set('color', 'black');

// Replace the metadata, keep the value
Attributes::for($product)->meta('color', ['hex' => '#f5f5f5', 'source' => 'import']);

// Clear it
Attributes::for($product)->meta('color', null);

// Model shorthand
$product->attachAttribute('color', 'white', collect(['hex' => '#ffffff']));
$product->syncAttributeMeta('color', collect(['hex' => '#f5f5f5']));

meta() — aj jeho skratka na modeli syncAttributeMeta() — nahradí celú kolekciu metadát daného atribútu a jeho hodnotu nechá bez zmeny; ak atribút ešte nie je pripojený, vytvorí riadok s hodnotou null. S null metadáta vymaže. Prechádza tým istým zápisom ako hodnota: uplatní sa prísny režim, história zaznamená revíziu a spustí sa AttributeAttached. Keďže hodnota zostáva bez zmeny, zlyhať môže len na prísnom režime.