Open source
Addresses for Laravel
composer require roundly-consulting/addresses-for-laravelPrehľad
Adresy pre akýkoľvek Eloquent model, natívne v Laraveli. Pridajte trait HasAddresses a pripojte toľko fakturačných, dodacích, domácich či kancelárskych adries, koľko potrebujete — všetky v jednej polymorfnej tabuľke addresses, vytvorené fluentným builderom alebo cez DTO, typované šiestimi vstavanými prípadmi AddressType alebo vašimi vlastnými typmi, s najviac jednou primárnou adresou na typ, povyšovanou atomicky, úpravami a mazaním s kontrolou vlastníka a s ISO kódmi krajín normalizovanými už pri zápise. Súčasťou sú query scopy, udalosti životného cyklu, API resource a testovacie pomôcky. Licencia MIT, postavené len na Laraveli a vlastnom package toolkite Roundly — bez závislostí tretích strán a bez sieťových volaní.
Čo získate
Adresy na akomkoľvek modeli
Jeden trait a jedna polymorfná tabuľka dajú akémukoľvek Eloquent modelu fakturačné, dodacie či kancelárske adresy — pre vlastníkov s bigint, UUID aj ULID kľúčmi.
Konfigurovateľné typy adries
Šesť vstavaných typov — default, billing, shipping, home, work, office — alebo váš vlastný zoznam v addresses.types. Typ mimo zoznamu zápis odmietne; popisky v angličtine aj slovenčine.
Jedna primárna na typ
Povýšenie adresy atomicky, pod zámkom skupiny vlastník + typ, zruší primárny príznak ostatným. Úprava, zmazanie aj setPrimary s kontrolou vlastníka adresu iného vlastníka odmietnu.
Fasáda, DI alebo akcie
Addresses::for($customer)->new()->in(…)->at(…)->save() sa číta ako veta; rovnaký výsledok dosiahnete aj cez AddressManager alebo akciu.
Normalizácia ISO krajín
Kódy sa pri zápise orežú, prevedú na veľké písmená a overí sa ich tvar. Názvy a geokódovanie doplní váš CountryResolver — bez sieťových volaní.
Udalosti, scopy a API resource
Štyri udalosti životného cyklu, query scopy primary/ofType/inCountry a stabilný AddressResource pre JSON API.
Zaznamenávajúci fake a pomôcky
Addresses::fake() zaznamená každý zápis bez zásahu do databázy; k tomu assertHasAddress(), assertPrimaryAddress() a AddressFactory.
Dokumentácia
Inštalácia
Inštalácia cez Composer, publikovanie a spustenie migrácie adries (typ kľúča UUID či ULID nastavte vopred) a voliteľne publikovanie config/addresses.php.
Konfigurácia
Každý konfiguračný kľúč a jeho predvolená hodnota — model adresy, typ kľúča vlastníka, typy adries, predvolený typ, normalizácia krajín, resolver a alias.
Databázová schéma a typy kľúčov
Tabuľka addresses stĺpec po stĺpci a ako key_type určuje polymorfný stĺpec vlastníka pre modely s kľúčmi bigint, UUID alebo ULID.
Trait HasAddresses
Pridajte HasAddresses akémukoľvek Eloquent modelu a získate polymorfný vzťah addresses a pomocníkov na vytváranie, čítanie a primárne adresy.
Typy adries
Šesť vstavaných prípadov AddressType alebo vlastné typy v addresses.types — zápis typ mimo zoznamu odmietne; popisky, ValidAddressType a výber typu.
Fasáda Addresses
Addresses::for($owner) vráti adresár vlastníka so zápismi s kontrolou vlastníka; ploché update, delete, types a countryName vlastníka nepotrebujú.
DI a akcie
Bez fasády: injektujte AddressManager alebo spustite niektorú zo štyroch akcií priamo — mapa metód fasády na akcie.
AddressData a CreateAddressAction
Zápisy cez DTO AddressData — make(), predvolené hodnoty a záložný default_type — alebo createAddress() a CreateAddressAction na akomkoľvek modeli.
Fluentný builder
Vytvárajte adresy cez Addresses::for()->new() alebo newAddress() — čitateľná reťaz PendingAddress, ktorá neprepustí neúplnú adresu.
Čítanie adries
Načítajte všetky adresy, prvú alebo primárnu adresu daného typu, kolekciu jedného typu alebo rýchlu kontrolu existencie.
Primárne adresy
Jedna primárna adresa na vlastníka a typ — povýšenie, zrušenie, nastavenie pri vytvorení a ochrana pred adresou iného vlastníka.
Query scopy
Filtrujte adresy scopmi primary(), ofType() a inCountry() — na modeli, na vzťahu ľubovoľného vlastníka alebo v kombinácii.
Model Address
Atribúty, casty, vzťah na vlastníka, JSON meta a jednoriadkový popis formatted() na modeli Address.
Úprava a mazanie
Úpravy s kontrolou vlastníka alebo bez nej s úplným AddressData, mäkké mazanie a obnova adries a upratanie, keď vlastník zanikne.
Kódy krajín a resolvery
Normalizácia ISO kódov krajín pri každom zápise a voliteľný CountryResolver pre názvy a geokódovanie — bez pribalených dát a sieťových volaní.
Udalosti
AddressCreated, AddressUpdated, AddressDeleted a PrimaryAddressChanged — kedy sa ktorá odošle, prečo čakajú na commit a ako ich počúvať.
API resource
AddressResource vykreslí adresu pre JSON API v stabilnom tvare — riadky adresy, krajina, primárny príznak, formátovaný popis a meta.
Vlastný model adresy
Cez konfiguráciu nasaďte vlastnú podtriedu Address so scopmi, vzťahmi či castmi — každá cesta balíka ju použije.
Výnimky
Jedna základná AddressesException a päť typovaných výnimiek — neúplná adresa, neplatná krajina, cudzia adresa, zmazaná adresa a neplatný typ.
Testovanie
Zaznamenávajúci Addresses::fake(), asercie InteractsWithAddresses, AddressFactory so stavmi billing, shipping a primary a príklad v Peste.
Požiadavky
PHP 8.4+ a Laravel 13 — bez PHP rozšírení, bez závislostí tretích strán a bez sieťových volaní.
Prejavte lásku k open source
Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.
Ďalšie spôsoby podpory vrátane kryptomienOdoslaním daru súhlasíte s našimi podmienkami prijímania darov.
Chcete to zabudovať do svojho produktu?
Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.