Jedinečnosť, povinnosť a predvolené hodnoty

Jedinečné hodnoty

Jedinečná definícia odmietne hodnotu, ktorú už má iný vlastník:

use RoundlyConsulting\Attributes\DataTransferObjects\AttributeDefinitionData;
use RoundlyConsulting\Attributes\Enums\AttributeType;
use RoundlyConsulting\Attributes\Enums\UniqueScope;
use RoundlyConsulting\Attributes\Facades\Attributes;

Attributes::define(new AttributeDefinitionData('sku', AttributeType::String_, unique: UniqueScope::Global_));

Attributes::for($a)->set('sku', 'ABC');
Attributes::for($b)->set('sku', 'ABC'); // throws DuplicateAttributeValueException
Attributes::for($a)->set('sku', 'ABC'); // re-saving the owner's own value is fine

Attributes::for($a)->forget('sku');
Attributes::for($b)->set('sku', 'ABC'); // fine — detaching freed the value

Opätovné uloženie vlastnej hodnoty toho istého vlastníka prejde bez chyby, odpojenie atribútu jeho hodnotu uvoľní a hodnoty null sa nekontrolujú. DuplicateAttributeValueException sprístupňuje attributeName a scope.

Jedinečnosť je zárukou databázy, nie len kontrolou pred zápisom: každá jedinečná hodnota nesie deterministický hash v stĺpci unique_hash s unikátnym indexom — dvaja súbežní zapisovatelia tej istej hodnoty nemôžu commitnúť obaja a ten pomalší dostane DuplicateAttributeValueException. Funguje to aj pre šifrované hodnoty: ich hash je kľúčovaný slepý index (HMAC pod kľúčom odvodeným z APP_KEY), takže databáza nikdy nedrží otvorený text. Rotácia APP_KEY tento kľúč zmení — šifrované jedinečné hodnoty potom uložte znova.

Povinné atribúty

Povinnosť sa vynucuje na požiadanie, nie pri každom pripojení — zavolajte validateAttributes() vo chvíli, keď má byť model úplný, napríklad na konci importu alebo kroku objednávky:

use RoundlyConsulting\Attributes\Exceptions\MissingRequiredAttributeException;

Attributes::define(new AttributeDefinitionData('rating', AttributeType::Integer, required: true));

try {
    $product->validateAttributes();
} catch (MissingRequiredAttributeException $e) {
    $e->attributeName; // 'rating'
}

validateAttributes() prejde všetky definície platné pre model, globálne aj deklarované na modeli. Pri prvom chýbajúcom povinnom atribúte vyhodí MissingRequiredAttributeException a každú prítomnú hodnotu znova overí voči typu a pravidlám.

Predvolené hodnoty

Predvolenú hodnotu z definície vracajú čítania, keď atribút nie je pripojený. Uplatňuje sa len pri čítaní — nikdy sa neukladá a hromadné getAttachedAttributes() obsahuje len uložené riadky:

Attributes::define(new AttributeDefinitionData('retries', AttributeType::Integer, default: 3));

Attributes::for($product)->get('retries'); // 3 when not attached, the stored value when set
$product->attributeInt('retries');         // 3
$product->attr('retries')->int();          // 3

Attributes::for($product)->set('retries', null);
Attributes::for($product)->get('retries'); // null — an explicitly stored null is not replaced

Atribút výslovne uložený s hodnotou null sa prečíta ako null — predvolená hodnota nastupuje len za atribút, ktorý nie je pripojený.