README

Polymorphic address management for any Eloquent model. Supports multiple addresses per model with flag-based retrieval (primary, billing, shipping) and country code validation against a seeded countries table.

Installation

composer require centrex/laravel-addresses
php artisan vendor:publish --tag="laravel-addresses-migrations"
php artisan migrate
php artisan db:seed --class="Centrex\Addresses\Database\Seeders\CountrySeeder"

Usage

1. Add the trait to your model

use Centrex\Addresses\Traits\HasAddresses;

class Customer extends Model
{
    use HasAddresses;
}

2. Add an address

The country field must be a valid ISO 3166-1 alpha-2 code present in the seeded countries table.

$customer->addAddress([
    'country_code' => 'BD',
    'city'         => 'Dhaka',
    'state'        => 'Dhaka Division',
    'post_code'    => '1000',
    'street'       => '123 Main Street',
    'is_primary'   => true,
    'is_billing'   => true,
]);

3. Retrieve addresses

// All addresses
$customer->addresses;

// Check if any addresses exist
$customer->hasAddresses();

// Get by flag (primary | billing | shipping)
$customer->getAddress('billing');    // returns flagged address or falls back
$customer->getAddress('shipping', strict: true);  // only flagged, no fallback

// Latest address (no flag filter)
$customer->getAddress();

4. Update and delete

$address = $customer->addresses->first();

$customer->updateAddress($address, ['city' => 'Chittagong']);

$customer->deleteAddress($address);

// Remove all
$customer->flushAddresses();

Deprecated helpers (use getAddress() instead)

$customer->getPrimaryAddress();
$customer->getBillingAddress();
$customer->getShippingAddress();

Testing

composer test        # full suite
composer test:unit   # pest only
composer test:types  # phpstan
composer lint        # pint

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• centrex
• All Contributors

License

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