centrex/laravel-addresses

Manage address in laravel

v1.2.3 2025-07-18 16:59 UTC

Requires

• php: ^8.2|^8.3|^8.4
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• webpatser/laravel-countries: ^1.5
• webpatser/laravel-uuid: ^3.0|^4.0

Requires (Dev)

• larastan/larastan: ^2.0
• laravel/pint: ^1.0
• nunomaduro/collision: ^8.5
• orchestra/testbench: ^9.5
• pestphp/pest: ^3.4
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• rector/rector: ^1.2
• spatie/laravel-ray: ^1.26

MIT

• centrex

• laravel
• laravel-addresses
• centrex

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'    => 'BD',
    'city'       => 'Dhaka',
    'state'      => 'Dhaka Division',
    'zip'        => '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.