Addresses for Laravel

Billing, shipping and other addresses on any Eloquent model through one polymorphic relation. Add the HasAddresses trait and attach as many typed addresses as you need, with one primary per owner and type (promoted atomically), country-code normalisation, query scopes and events.

Installation

Requires PHP 8.4 and Laravel 12 or 13.

composer require roundly-consulting/addresses-for-laravel
php artisan vendor:publish --tag="addresses-migrations"
php artisan migrate

If the models that own addresses have UUID/ULID keys, set ADDRESSES_KEY_TYPE before migrating.

Usage

Give a model an address book:

use Illuminate\Database\Eloquent\Model;
use RoundlyConsulting\Addresses\Traits\HasAddresses;

class Customer extends Model
{
    use HasAddresses;
}

Add an address and read it back:

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

Addresses::for($customer)->new()
    ->type(AddressType::Shipping)
    ->name('Home')
    ->primary()                                   // demotes the previous primary shipping address
    ->in('Bratislava')->at('Somewhere 1')->postalCode('81101')->country('sk')
    ->save();

$address = Addresses::for($customer)->primary(AddressType::Shipping);

$address->country_iso;                            // 'SK' — normalised on the way in
$address->formatted();                            // 'Home, Somewhere 1, 81101 Bratislava, SK'
Addresses::for($customer)->ofType(AddressType::Shipping);   // Collection<Address>

Documentation

The full documentation — configuration, every feature and its API, and testing — lives on our website: roundly-consulting.com/open-source/docs/addresses-for-laravel

Release notes are in CHANGELOG.md. To contribute, see the contributing guide.

Support our work

This package is free and open source, built and maintained by Roundly Consulting. If it saves you time, please consider supporting our open-source work — a one-time donation, a monthly pledge on Patreon or a crypto donation helps fund maintenance, new features and new packages.

License

The MIT License (MIT). Please see LICENSE for more information.