PHPackages                             blamodex/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. blamodex/laravel-addresses

ActiveLibrary[Utility & Helpers](/categories/utility)

blamodex/laravel-addresses
==========================

Address management package for Laravel applications.

v1.0.0(5mo ago)274MITPHPPHP ^8.2

Since Nov 8Pushed 5mo agoCompare

[ Source](https://github.com/blamodex/laravel-addresses)[ Packagist](https://packagist.org/packages/blamodex/laravel-addresses)[ Docs](https://github.com/blamodex/laravel-addresses)[ RSS](/packages/blamodex-laravel-addresses/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (10)Versions (5)Used By (0)

Blamodex Laravel Addresses
==========================

[](#blamodex-laravel-addresses)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![Laravel](https://camo.githubusercontent.com/49180e08c9d2bf7321e8c7b5e2e6d04688dfe7dc215442c6e87bb62a1943800c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31322d7265642e737667)](https://laravel.com)[![PHP](https://camo.githubusercontent.com/0f16581d1180dbfd4c0e13166ec1267d4ad2f2fab8281ea6d6b284cf5c65d921/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d626c75652e737667)](https://www.php.net/)[![Tests](https://camo.githubusercontent.com/471c02a19701f7ef49babbe0efc80d5ece38362cd089c4db9f6f5e3900a6db91/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54657374732d353725323070617373696e672d627269676874677265656e2e737667)](https://github.com/blamodex/laravel-addresses)

A lightweight Laravel package to manage postal addresses, countries and administrative areas, suitable for attaching addresses to any Eloquent model using polymorphic relationships.

📋 Table of Contents
-------------------

[](#-table-of-contents)

- [Features](#-features)
- [Installation](#-installation)
- [Configuration](#%EF%B8%8F-configuration)
- [Usage](#-usage)
- [Testing](#-testing)
- [Project Structure](#-project-structure)
- [Contributing](#-contributing)
- [License](#-license)

---

🚀 Features
----------

[](#-features)

- Polymorphic `Address` model attachable to any Eloquent model via a trait
- Lookup tables for `Country` and `AdministrativeArea` with seeders and migrations
- Postal code normalization for US and Canada via (`PostalCodeFormatter`) with a clear, nullable contract
- DB-backed `AddressValidator` to validate country, administrative area and postal codes
- Service layer (`AddressService`) for create/update/delete/list operations
- Soft deletes, UUID generation, and test coverage via Orchestra Testbench

---

📦 Installation
--------------

[](#-installation)

Install the package with Composer:

```
composer require blamodex/laravel-addresses
```

Publish the config file:

```
php artisan vendor:publish --tag=blamodex-address-config
```

Run the migrations:

```
php artisan migrate
```

---

⚙️ Configuration
----------------

[](#️-configuration)

Configuration lives in `config/address.php` (empty by default, but you can add options for formatting or validation):

```
return [
    // e.g. 'default_country' => 'CA'
];
```

---

🧩 Usage
-------

[](#-usage)

### 1. Use the `Addressable` trait on models

[](#1-use-the-addressable-trait-on-models)

For models that can have addresses:

```
use Blamodex\Address\Traits\Addressable;
use Blamodex\Address\Contracts\AddressableInterface;

class User extends Model implements AddressableInterface
{
    use Addressable;
}
```

### 2. Create an address

[](#2-create-an-address)

```
$user = User::find(1);

// Using the trait method
$address = $user->createAddress([
    'address_1' => '100 Main St',
    'city' => 'Anytown',
    'administrative_area_code' => 'CA',
    'postal_code' => '90001',
    'country_code' => 'US',
]);

// Or using the service directly
$service = app(\Blamodex\Address\Services\AddressService::class);
$address = $service->create($user, $attributes);
```

### 3. Update an address

[](#3-update-an-address)

```
$user->updateAddress($address, ['address_1' => '200 Main St']);

// Or via service
$service->update($address, ['address_1' => '200 Main St']);
```

### 4. Delete an address

[](#4-delete-an-address)

```
$user->deleteAddress($address);

// Or via service
$service->delete($address);
```

### 5. Validation

[](#5-validation)

Use the `AddressValidator` to check attributes before persisting:

```
$errors = \Blamodex\Address\Validators\AddressValidator::validate($attributes);
// Or throw on error
\Blamodex\Address\Validators\AddressValidator::validateOrFail($attributes);
```

`PostalCodeFormatter::format()` accepts `?string` and returns `?string` — `null` indicates invalid or unsupported postal code.

---

🧪 Testing
---------

[](#-testing)

This package uses [Orchestra Testbench](https://github.com/orchestral/testbench) and [PHPUnit](https://phpunit.de/).

Run tests:

```
composer test
```

Run tests with code coverage:

```
composer test:coverage
```

Check code style:

```
composer lint
```

Check code style and fix:

```
composer lint:fix
```

Check static analysis (phpstan) and tests as part of CI as configured in the repo.

---

📁 Project Structure
-------------------

[](#-project-structure)

```
src/
├── Models/
│   ├── Address.php
│   ├── Country.php
│   └── AdministrativeArea.php
├── Services/
│   └── AddressService.php
├── Traits/
│   └── Addressable.php
├── Contracts/
│   └── AddressableInterface.php
├── Validators/
│   └── AddressValidator.php
├── Utils/
│   └── PostalCodeFormatter.php
├── config/
│   └── address.php
└── database/
    ├── migrations/
    └── seeders/

tests/
├── Unit/
│   ├── AddressServiceTest.php
│   ├── AddressTest.php
│   ├── AdministrativeAreaTest.php
│   ├── CountryTest.php
│   ├── PostalCodeFormatterTest.php
│   └── AddressValidatorTest.php
├── Fixtures/
│   ├── DummyAddressUser.php
│   └── DummyAddressCompany.php
└── TestCase.php

```

---

📄 License
---------

[](#-license)

MIT © [Blamodex](https://github.com/blackmage-codex)

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

🔗 Links
-------

[](#-links)

- [Report a Bug](https://github.com/blamodex/laravel-addresses/issues)
- [Request a Feature](https://github.com/blamodex/laravel-addresses/issues)
- [View Changelog](CHANGELOG.md)

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance71

Regular maintenance activity

Popularity15

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 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.

###  Release Activity

Cadence

Every ~10 days

Total

3

Last Release

164d ago

Major Versions

v0.2.0-beta.1 → v1.0.02025-11-29

### Community

Maintainers

![](https://www.gravatar.com/avatar/4f55d38385fa6cea42e03e9f4d95bbb789c6c0492de1e386b60e5f2836c96d5d?d=identicon)[blamodex](/maintainers/blamodex)

---

Top Contributors

[![blackmage-codex](https://avatars.githubusercontent.com/u/218423009?v=4)](https://github.com/blackmage-codex "blackmage-codex (27 commits)")

---

Tags

laravelgeocodingaddresspostallocationcountryaddresses

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/blamodex-laravel-addresses/health.svg)

```
[![Health](https://phpackages.com/badges/blamodex-laravel-addresses/health.svg)](https://phpackages.com/packages/blamodex-laravel-addresses)
```

###  Alternatives

[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[psalm/plugin-laravel

Psalm plugin for Laravel

3274.9M308](/packages/psalm-plugin-laravel)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[laragear/preload

Effortlessly make a Preload script for your Laravel application.

119363.5k](/packages/laragear-preload)[flarum/core

Delightfully simple forum software.

211.3M1.9k](/packages/flarum-core)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)