Download the PHP package masterix21/laravel-addressable without Composer

Make your Eloquent models addressable

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:

Publish and run the migrations:

Optionally publish the config file:

Upgrading from 2.1.x

Publish and run the additional meta column migration:

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:

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:

Usage

Attach addresses to a model

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

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

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.

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

Inverse relationship

Metadata

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

Display address

The display_address accessor returns a readable representation:

Customize the format in config/addressable.php:

Geospatial features

Store coordinates

Filter by distance

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

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

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.

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.

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:

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

Reverse geocode coordinates

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:

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:

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

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 [email protected] 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.