PHPackages blax-software/laravel-addresses - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. blax-software/laravel-addresses ActiveLibrary[Utility & Helpers](/categories/utility) blax-software/laravel-addresses =============================== Universal Laravel address management system — from rural coordinates to skyscraper rooms, worldwide. 14↓100%PHP Since May 12Pushed 4w agoCompare [ Source](https://github.com/blax-software/laravel-addresses)[ Packagist](https://packagist.org/packages/blax-software/laravel-addresses)[ RSS](/packages/blax-software-laravel-addresses/feed)WikiDiscussions master Synced 1w ago READMEChangelogDependenciesVersions (1)Used By (0) [![Blax Software OSS](https://raw.githubusercontent.com/blax-software/laravel-workkit/master/art/oss-initiative-banner.svg)](https://github.com/blax-software) Laravel Addresses ================= [](#laravel-addresses) [![PHP Version](https://camo.githubusercontent.com/cc9cdea9aa96b40a822425e981b0a030e3371202973c7d57b74e8e99834f81dc/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d626c7565)](https://php.net)[![Laravel](https://camo.githubusercontent.com/7368f99d085dbbf9427a12a968ccf661c64eaacb5879be697f5bb8b2c6efbf44/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d392e782d2d31322e782d6f72616e6765)](https://laravel.com) Universal Laravel address management — from rural GPS coordinates to specific rooms inside skyscrapers, worldwide. Overview -------- [](#overview) This package provides a complete address management system for Laravel applications built on a **three-layer architecture**: ``` Address → The physical place (street, city, coordinates …) └── AddressLink → Connects an address to a model with a purpose (User's "Office") └── AddressAssignment → References a link from another context (Job's "pickup") ``` **Example:** A user has an office address. A job references that office as its pickup location — without duplicating the address data. Features -------- [](#features) - **15 address fields** — street-level to room-level precision, with GPS coordinates (WGS-84) and altitude - **Polymorphic links** — attach addresses to any Eloquent model - **17 built-in link types** — Home, Office, Shipping, Billing, Warehouse and more - **Address assignments** — reference someone else's address in another context - **Temporal validity** — `active_from` / `active_until` on every link - **AddressService** — distance calculations (Haversine), proximity queries, duplicate detection, coordinate conversion - **Auto-geocoding** — saves call Nominatim (OpenStreetMap) for lat/lon, serialized by a Cache lock and paced at 1 req/sec - **Fully configurable** — custom model classes, table names, default link type - **Soft deletes** on addresses, cascade deletes on links and assignments Requirements ------------ [](#requirements) - PHP 8.1+ - Laravel 9, 10, 11 or 12 - `blax-software/laravel-workkit` (installed automatically) Installation ------------ [](#installation) ``` composer require blax-software/laravel-addresses ``` Publish and run the migrations: ``` php artisan vendor:publish --tag="addresses-migrations" php artisan migrate ``` Optionally publish the config: ``` php artisan vendor:publish --tag="addresses-config" ``` Quick Start ----------- [](#quick-start) ### 1. Add the trait to your model [](#1-add-the-trait-to-your-model) ``` use Blax\Addresses\Traits\HasAddresses; class User extends Model { use HasAddresses; } ``` ### 2. Create and attach an address [](#2-create-and-attach-an-address) ``` use Blax\Addresses\Enums\AddressLinkType; $link = $user->addAddress([ 'street' => '350 Fifth Avenue', 'city' => 'New York', 'state' => 'NY', 'postal_code' => '10118', 'country_code' => 'US', 'latitude' => 40.748817, 'longitude' => -73.985428, ], AddressLinkType::Office); ``` ### 3. Query addresses [](#3-query-addresses) ``` $user->addresses; // all addresses $user->addressesOfType(AddressLinkType::Office); // only offices $user->primaryAddress(); // primary across all types $user->activeAddressLinks(); // only currently active links ``` ### 4. Assign an address to another model [](#4-assign-an-address-to-another-model) ``` use Blax\Addresses\Traits\HasAddressAssignments; class Job extends Model { use HasAddressAssignments; } $job->assignAddressLink($link, 'pickup'); $job->assignedAddressForRole('pickup'); // → the Address model ``` ### 5. Automatic geocoding (opt-in) [](#5-automatic-geocoding-opt-in) Set `ADDRESSES_GEOCODING_ENABLED=true` to have an observer ask Nominatim (OpenStreetMap) for `latitude` / `longitude` after every save. Calls are serialized cluster-wide through a `Cache::lock` and paced at 1 req/sec to honour the OSMF usage policy. **Off by default** so an upgrade doesn't surprise existing apps with new outbound HTTP traffic. ``` # .env ADDRESSES_GEOCODING_ENABLED=true # OSMF policy: identify your app — generic UAs get blocked. ADDRESSES_GEOCODING_USER_AGENT="my-app (https://example.com)" ADDRESSES_GEOCODING_EMAIL="ops@example.com" ``` ``` $address = Address::create([ 'street' => 'Stephansplatz 1', 'postal_code' => '1010', 'city' => 'Vienna', 'country_code' => 'AT', ]); // Observer has filled these in by the time create() returns. $address->refresh(); $address->latitude; // 48.2082… $address->longitude; // 16.3738… ``` Tunable knobs (see [`config/addresses.php`](config/addresses.php) → `geocoding`): - `enabled` — master switch (env: `ADDRESSES_GEOCODING_ENABLED`) - `driver` — only `nominatim` ships out of the box, but you can rebind the `Geocoder` contract to plug in Google Maps / Mapbox / Mapquest / a self-hosted Nominatim - `update_only_when_missing` — leave manually-entered coordinates alone - `min_interval_seconds` — global ceiling on outbound traffic (default `1.0`, matches Nominatim's published policy) - `lock_wait_seconds`, `lock_ttl_seconds` — Cache lock parameters - `accept_language` — Nominatim's `display_name` localization - `drivers.nominatim.user_agent` / `email` — required by Nominatim for attribution; set both in production For tests / imports, disable per-environment with `ADDRESSES_GEOCODING_ENABLED=false` (or `config()->set('addresses.geocoding.enabled', false)` inside a TestCase hook). ### 6. Use the AddressService [](#6-use-the-addressservice) ``` // Via helper $distance = address()->distanceBetween($addressA, $addressB); // km // Nearby addresses within 10 km $nearby = address()->nearby(48.2082, 16.3738, 10); // Format for display echo address()->formatMultiline($address); ``` Documentation ------------- [](#documentation) GuideDescription[Installation & Configuration](docs/installation.md)Setup, publishing, config options[Core Concepts](docs/core-concepts.md)The three-layer architecture explained[HasAddresses Trait](docs/has-addresses.md)Full API for address-owning models[HasAddressAssignments Trait](docs/has-address-assignments.md)Full API for address-consuming models[AddressService](docs/address-service.md)Distance, proximity, formatting, conversion[Geocoding](docs/geocoding.md)Auto lat/lon via Nominatim, cache lock, rate limit[AddressLinkType Enum](docs/address-link-types.md)All 17 built-in types with descriptions[Customization](docs/customization.md)Extending models, custom tables, overriding defaultsTesting ------- [](#testing) ``` composer test ``` License ------- [](#license) MIT Star History ------------ [](#star-history) [ ![Star History Chart](https://camo.githubusercontent.com/18d1ba08a425cfef49b558e22bff6271f11beefbfa8f749b768b7bdb11e5df3f/68747470733a2f2f6170692e737461722d686973746f72792e636f6d2f63686172743f7265706f733d626c61782d736f6674776172652f6c61726176656c2d61646472657373657326747970653d64617465266c6567656e643d746f702d6c656674) ](https://www.star-history.com/?repos=blax-software%2Flaravel-addresses&type=date&legend=top-left) ### Health Score 22 — LowBetter than 22% of packages Maintenance62 Regular maintenance activity Popularity7 Limited adoption so far Community6 Small or concentrated contributor base Maturity11 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/2d548acfc3520e2f810e35cfb78230f885befda9fa26a3be42353723c48f991e?d=identicon)[blax-software](/maintainers/blax-software) --- Top Contributors [![justsomexanda](https://avatars.githubusercontent.com/u/48434066?v=4)](https://github.com/justsomexanda "justsomexanda (7 commits)") ### Embed Badge ![Health badge](/badges/blax-software-laravel-addresses/health.svg) ``` [![Health](https://phpackages.com/badges/blax-software-laravel-addresses/health.svg)](https://phpackages.com/packages/blax-software-laravel-addresses) ``` ### Alternatives [genealabs/php-coding-standards 1655.3k1](/packages/genealabs-php-coding-standards)[falseclock/advanced-cms A PHP Library that allows you to decode and manipulate CAdES or in other words CMS Advanced Electronic Signatures described in ETSI standart TS 101 733. 223.4k](/packages/falseclock-advanced-cms) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)