README

Attach any number of addresses to any Eloquent model through a polymorphic relation. Built on top of matanyadaev/laravel-eloquent-spatial, it natively supports geospatial coordinates and distance queries — perfect for billing, shipping or any location-aware use case.

Features

• Polymorphic addresses() relation for any Eloquent model
• Dedicated billing and shipping traits with primary-address shortcuts
• Eager-loadable primaryAddress, billingAddress, shippingAddress relations
• Primary-address toggling, scoped per address type, with events
• Geospatial POINT column with distance queries, withinRadius scope and optional spatial index
• Free-form meta JSON column for extra data
• Configurable display_address accessor
• SoftDeletes-aware cascade delete of addresses when the parent model is deleted
• Pluggable Address model and table name

Requirements

• PHP 8.2+
• Laravel 11.x, 12.x or 13.x (Laravel 13 requires PHP 8.3+)
• A database with spatial support (MySQL 8+, MariaDB 10.5+, PostgreSQL with PostGIS)

Support us

If you like my work, you can sponsor me.

Installation

Install the package via Composer:

composer require masterix21/laravel-addressable

Publish and run the migrations:

php artisan vendor:publish --provider="Masterix21\Addressable\AddressableServiceProvider" --tag="migrations"
php artisan migrate

Optionally publish the config file:

php artisan vendor:publish --provider="Masterix21\Addressable\AddressableServiceProvider" --tag="config"

Upgrading from 2.1.x

Publish and run the additional meta column migration:

php artisan vendor:publish --provider="Masterix21\Addressable\AddressableServiceProvider" --tag="addressable-meta-migration"
php artisan migrate

Upgrading from 2.2.x

Spatial index (optional but recommended). Publish and run the spatial index migration to make coordinates indexed for fast distance queries:

php artisan vendor:publish --provider="Masterix21\Addressable\AddressableServiceProvider" --tag="addressable-spatial-index-migration"
php artisan migrate

The migration:

• Backfills any row with NULL coordinates to POINT(0, 0) with the configured SRID.
• Alters coordinates to NOT NULL with a POINT(0, 0) default, so addresses created without explicit coordinates keep working.
• Adds a SPATIAL INDEX on coordinates.

primaryAddress is now a relation. It used to be a method returning ?Address. It now returns a MorphOne relation, which means:

• $user->primaryAddress still returns ?Address (unchanged via property access).
• $user->primaryAddress() now returns a relation builder, not the model. If you were calling it as a method, switch to the property or append ->first().
• You can now eager load it: User::with('primaryAddress')->get().

Configuration

The published config/addressable.php file exposes:

return [
    'models' => [
        // Swap with your own model (e.g. to use UUIDs).
        'address' => \Masterix21\Addressable\Models\Address::class,
    ],

    'tables' => [
        // Change before running the migration.
        'addresses' => 'addresses',
    ],

    // SRID used for the POINT column. 4326 = WGS84 (lat/lng).
    'srid' => 4326,

    // Template for the display_address accessor. Use {field_name} placeholders.
    // Set to null to fall back to the default " - " separated format.
    'display_format' => null,
];

Usage

Attach addresses to a model

use Masterix21\Addressable\Models\Concerns\HasAddresses;

class User extends Model
{
    use HasAddresses;
}

$user->addresses; // MorphMany of Masterix21\Addressable\Models\Address

HasAddresses is the generic trait. For billing or shipping flows, use the dedicated traits (they can be combined):

use Masterix21\Addressable\Models\Concerns\HasBillingAddresses;
use Masterix21\Addressable\Models\Concerns\HasShippingAddresses;

class User extends Model
{
    use HasBillingAddresses, HasShippingAddresses;
}

$user->billingAddress;    // Primary billing address (MorphOne)
$user->billingAddresses;  // All billing addresses (MorphMany)

$user->shippingAddress;   // Primary shipping address (MorphOne)
$user->shippingAddresses; // All shipping addresses (MorphMany)

When the parent model is hard-deleted, its addresses are automatically removed. If the parent uses SoftDeletes, addresses survive soft-delete and are removed only on forceDelete().

Create addresses

// Generic address
$user->addAddress([
    'label' => 'Home',
    'street_address1' => 'Via Roma 1',
    'zip' => '20100',
    'city' => 'Milan',
    'state' => 'MI',
    'country' => 'IT',
]);

// Billing address — is_billing is set automatically
$user->addBillingAddress([
    'street_address1' => 'Via Roma 1',
    'city' => 'Milan',
]);

// Shipping address — is_shipping is set automatically
$user->addShippingAddress([
    'street_address1' => 'Via Roma 1',
    'city' => 'Milan',
]);

// Fetch the primary address (any type) via the eager-loadable relation
$user->primaryAddress;                  // ?Address
User::with('primaryAddress')->get();    // eager loaded

Address fields

Mark an address as primary

markPrimary() ensures a single primary address per type, scoped to the same parent model. It is wrapped in a transaction and unmarks any other primary address of the same kind.

$shippingAddress->markPrimary();
$shippingAddress->unmarkPrimary();

$billingAddress->markPrimary();
$billingAddress->unmarkPrimary();

Events

Every primary toggle dispatches dedicated events (each carrying the Address instance):

All events live in Masterix21\Addressable\Events. Billing/shipping variants fire only when the respective flag is set on the address.

Query scopes

use Masterix21\Addressable\Models\Address;

Address::query()->primary()->get();
Address::query()->billing()->get();
Address::query()->shipping()->get();

// Scopes are composable
Address::query()->billing()->primary()->first();

Inverse relationship

$address->addressable; // The parent model (User, Company, ...)

Metadata

Every address has a JSON meta column for extra data without touching the schema:

$user->addAddress([
    'street_address1' => 'Via Roma 1',
    'city' => 'Milan',
    'meta' => [
        'phone' => '+39 02 1234567',
        'floor' => 3,
        'notes' => 'Ring twice',
    ],
]);

$address->meta['phone']; // '+39 02 1234567'

Display address

The display_address accessor returns a readable representation:

$address->display_address; // "Via Roma 1 - 20100 - Milan - MI - IT"

Customize the format in config/addressable.php:

'display_format' => '{street_address1}, {street_address2}, {zip} {city}, {state}, {country}',

Geospatial features

Store coordinates

use MatanYadaev\EloquentSpatial\Objects\Point;

$user->addBillingAddress([
    'street_address1' => 'Via Antonio Izzi de Falenta, 7/C',
    'zip' => '88100',
    'city' => 'Catanzaro',
    'state' => 'CZ',
    'country' => 'IT',
    'coordinates' => new Point(38.90852, 16.5894, config('addressable.srid')),
]);

// Or assign later
$billingAddress->coordinates = new Point(38.90852, 16.5894, config('addressable.srid'));
$billingAddress->save();

Filter by distance

Use the withinRadius scope for the common case of "addresses within N meters of a point":

use MatanYadaev\EloquentSpatial\Objects\Point;

$milano = new Point(45.4391, 9.1906, config('addressable.srid'));

// Addresses within 10 km of Milan
Address::query()->withinRadius($milano, 10_000)->get();

For custom comparisons (<, >=, etc.) drop down to the underlying spatial scope:

Address::query()
    ->whereDistanceSphere(
        column: 'coordinates',
        geometryOrColumn: $milano,
        operator: '>=',
        value: 10_000,
    )
    ->get();

Add distance as a column

addDistanceTo() appends the distance from a given point (always in meters) as an extra column. Divide by 1000 for kilometers, by 1609.344 for miles.

$origin = new Point(45.4642, 9.1900, config('addressable.srid'));

// Default column name: `distance`
$addresses = Address::query()
    ->addDistanceTo($origin)
    ->get();

$addresses->first()->distance; // e.g. 1523.4

// Custom column name
Address::query()->addDistanceTo($origin, as: 'dist_meters')->get();

// Nearest first
Address::query()->addDistanceTo($origin)->orderBy('distance')->get();

Order by distance and find nearest

orderByDistance() sorts addresses by distance from a point without adding any column. nearest() is the high-level helper for "give me the N closest addresses": it adds the distance column, orders ascending and optionally applies a limit.

$milano = new Point(45.4642, 9.1900, config('addressable.srid'));

// The 5 addresses closest to Milan, each with a populated `distance` (meters)
$closest = Address::query()->nearest($milano, 5)->get();

$closest->first()->distance; // e.g. 42.1

// Composable with any other scope
Address::query()->billing()->nearest($milano, 3)->get();

// Without a limit, ordering is applied but the result set is not truncated
Address::query()->shipping()->nearest($milano)->paginate(20);

// Ordering only, no `distance` column
Address::query()->orderByDistance($milano, 'desc')->get();

Geocoding

Geocoding turns a textual address into coordinates, and reverse geocoding does the opposite. Drivers are tried in order (FIFO): the first one returning a result wins, so a failing driver falls back to the next.

Two keyless drivers ship enabled by default: Nominatim (OpenStreetMap) and Photon (Komoot).

Google driver

A Google driver is provided as well. It is commented out in config/addressable.php — uncomment its entry and set GOOGLE_GEOCODER_KEY:

// config/addressable.php
'geocoding' => [
    'drivers' => [
        'google' => [
            'class' => \Masterix21\Addressable\Geocoding\Drivers\GoogleGeocoder::class,
            'endpoint' => 'https://maps.googleapis.com/maps/api/geocode/json',
            'api_key' => env('GOOGLE_GEOCODER_KEY'),
        ],
        'nominatim' => [/* ... */],
        'photon' => [/* ... */],
    ],
],

Drivers are tried in array order, so placing google first makes it the primary driver with Nominatim and Photon as fallbacks. The Google driver uses the Geocoding API for both forward and reverse geocoding, and treats any response whose status is not OK as a miss (falling through to the next driver).

Geocode an address

$address = $user->addAddress([
    'street_address1' => 'Via Roma 1',
    'zip' => '20100',
    'city' => 'Milan',
    'country' => 'IT',
]);

if ($address->geocode()) {  // fills `coordinates`, does not persist
    $address->save();
}

Reverse geocode coordinates

$address->coordinates = new Point(45.4642, 9.19, config('addressable.srid'));

if ($address->reverseGeocode()) {  // fills street/zip/city/state/country
    $address->save();
}

Both methods emit the AddressGeocoded event on success.

Automatic geocoding

Enable addressable.geocoding.auto (or ADDRESSABLE_GEOCODER_AUTO=true) to geocode addresses saved without coordinates automatically:

// With auto enabled, coordinates are resolved on save
$user->addAddress([
    'street_address1' => 'Via Roma 1',
    'city' => 'Milan',
    'country' => 'IT',
]);

When enabled, the addressable.geocoding.job is dispatched for every address saved without coordinates. The default GeocodeAddressJob job runs synchronously. To geocode on a queue instead — recommended for web requests, so the geocoder HTTP call doesn't block the response — extend the job and point the config at your subclass:

use Illuminate\Contracts\Queue\ShouldQueue;
use Masterix21\Addressable\Jobs\GeocodeAddressJob;

class QueuedGeocodeAddressJob extends GeocodeAddressJob implements ShouldQueue
{
}

// config/addressable.php
'geocoding' => [
    'job' => \App\Jobs\QueuedGeocodeAddressJob::class,
],

Note: Nominatim and Photon are free public services with a usage policy (Nominatim limits to ~1 request/second). For high volume, use Google or a self-hosted instance, and throttle bulk geocoding on your side.

Custom drivers

Implement Masterix21\Addressable\Geocoding\Contracts\Geocoder and add it to addressable.geocoding.drivers. Each driver receives its own config block (plus the shared srid and user_agent).

AI guidelines (Laravel Boost)

This package ships Laravel Boost guidelines. If your app uses Boost, run php artisan boost:install (or php artisan boost:update --discover) and select laravel-addressable to give your AI agent package-specific instructions.

Testing

composer test

Run the suite in parallel with composer test-parallel.

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email l.longo@ambita.it instead of using the issue tracker.

Credits

• Luca Longo
• Matan Yadaev
• All Contributors

License

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