Primárne adresy

Každý vlastník má najviac jednu primárnu adresu na typ — zákazník tak môže mať súčasne primárnu fakturačnú aj primárnu dodaciu adresu. Povýšenie jednej adresy — cez setPrimary() alebo pridaním či úpravou adresy s isPrimary: true / ->primary() — zruší primárny príznak ostatným v tej istej skupine vlastník + typ, a to v jednej transakcii pod zámkom skupiny: zlyhanie v polovici ponechá pôvodnú primárnu adresu a dve súbežné povýšenia nemôžu vyhrať obe:

use RoundlyConsulting\Addresses\Enums\AddressType;
use RoundlyConsulting\Addresses\Facades\Addresses;

$address = Addresses::for($payer)->ofType(AddressType::Office)->first();

Addresses::for($payer)->setPrimary($address);   // promote this, demote siblings
$payer->setPrimaryAddress($address);            // trait shortcut, same guard

primaryAddress() bez typu vráti prvú primárnu adresu ľubovoľného typu; ak chcete konkrétnu, zadajte typ.

Primárna už pri vytvorení

Adresu označte ako primárnu už pri vytváraní — cez ->primary() v builderi alebo isPrimary: true v AddressData — a ostatné adresy rovnakého typu stratia príznak v tom istom kroku:

use RoundlyConsulting\Addresses\Enums\AddressType;

$customer->newAddress()
    ->type(AddressType::Shipping)
    ->in('Košice')->at('Main 2')->postalCode('04001')->country('SK')
    ->primary()                     // the previous primary shipping address is demoted
    ->save();

$customer->primaryAddress(AddressType::Shipping);   // the address just saved

Kontrola vlastníctva

Metóda setPrimary() adresára — aj skratka setPrimaryAddress() — najprv overí, že adresa patrí vlastníkovi: addressable_type uloženého záznamu sa musí zhodovať s getMorphClass() a addressable_id s kľúčom vlastníka — kópii, ktorú odovzdáte, sa nikdy neverí. Inak vyhodí AddressOwnershipException, takže id adresy z requestu nikdy nepreusporiada adresy iného vlastníka:

use RoundlyConsulting\Addresses\Exceptions\AddressOwnershipException;
use RoundlyConsulting\Addresses\Facades\Addresses;

try {
    Addresses::for($customer)->setPrimary($otherCustomersAddress);
} catch (AddressOwnershipException $e) {
    abort(403);   // 'The given address does not belong to this model.'
}

Zmazané adresy

Mäkko zmazaná adresa sa primárnou stať nemôže — setPrimary() vyhodí TrashedAddressException (adresu najprv obnovte); aj to sa overuje voči uloženému záznamu. Po zmazaní primárnej adresy zostane jej typ bez primárnej, kým nepovýšite inú. Zmazaná adresa si príznak ponechá, takže restore() zmazanie vráti späť: ako primárna sa vráti, len kým skupina vlastník + typ nemá inú živú primárnu adresu; inak sa vráti ako bežná adresa:

use RoundlyConsulting\Addresses\Exceptions\TrashedAddressException;
use RoundlyConsulting\Addresses\Facades\Addresses;

Addresses::delete($address);   // the primary — its type has none until you promote another

try {
    Addresses::for($customer)->setPrimary($address);
} catch (TrashedAddressException $e) {
    // 'A deleted address cannot be made primary; restore it first.'
}

$address->restore();           // back as the primary while no other live primary holds the slot

Zrušenie primárnej adresy

Verejné volanie, ktoré by zrušilo primárny príznak celej skupine, neexistuje. Ak chcete zrušiť príznak jednej adrese, upravte ju s isPrimary: false; úprava je úplný zápis, preto preneste všetky ostatné polia:

use RoundlyConsulting\Addresses\DataTransferObjects\AddressData;
use RoundlyConsulting\Addresses\Facades\Addresses;

// demote one address — a full write, so carry over every other field
Addresses::update($address, AddressData::make(
    city: $address->city,
    street: $address->street,
    postalCode: $address->postal_code,
    countryIso: $address->country_iso,
    name: $address->name,
    type: $address->type,
    isPrimary: false,
    meta: $address->meta,
));

Udalosť PrimaryAddressChanged

PrimaryAddressChanged sa odošle vždy, keď sa adresa stane primárnou adresou svojho typu — cez setPrimary() či setPrimaryAddress(), pridaním s isPrimary: true alebo ->primary(), prípadne úpravou s isPrimary: true. Odošle sa po AddressCreated / AddressUpdated, keď je povýšenie zapísané, a nie, ak adresa primárna už bola.

Zápisy mimo balíka — priame create() či update() v Eloquente, factories — ostatným adresám príznak nezrušia. Na PostgreSQL a SQLite druhú živú primárnu adresu odmietne čiastočný unikátny index; na iných databázach takému zápisu nič nebráni.