Delivery Address Bundle Laravel Package

Getting Started

The 1.1.0 release ships with only a compare link rather than curated notes, so your first 10 minutes should be spent reading the diff (1.0.1...1.1.0) before installing. Minor-version bumps in address packages are usually additive — new validation rules, extra config keys, a new column — but confirm nothing touches existing migration columns or model fillables, since those are the two places a "minor" bump can silently break production.

Installation and first run, assuming the conventional Laravel package layout:

composer require tourze/delivery-address-bundle
php artisan vendor:publish --tag=delivery-address-config   # check tag names in the service provider
php artisan migrate

Look at these files in this order:

1. config/delivery-address.php — the contract for which model, table, and address fields the package uses. If 1.1.0 added keys here, republish or diff the config; published configs are not updated automatically.
2. The service provider's register()/boot() — reveals bindings, route registration, and whether routes/migrations are publishable or auto-loaded.
3. src/Models/ — the address entity and its relationships (morph to user/order is the common design).
4. src/Rules/ or src/Http/Requests/ — the validation surface, which is what you'll most often want to extend.

First use case: attach an address to a user and render a checkout form. The minimum viable flow is create an address for the authenticated user, mark one as default, and resolve $user->defaultAddress (or the package's equivalent accessor) at checkout. Get that working end-to-end before wiring in country/region data or geocoding — those are the parts most likely to need customization anyway.

Implementation Patterns

Treat the package model as a base, not the model. The durable pattern is to publish/extend the shipped address model into App\Models\Address and re-point the config's model binding at yours. You keep the package's traits, casts, and validation while owning the place where you add tenant scoping, soft deletes, or a label column. Subclassing is safer than editing vendor code and survives composer update.

Checkout flow with a default-address invariant. The usual workflow is: user has many addresses, exactly one is default. Do the "set default" operation inside a transaction and clear the previous default in the same statement — the package may expose a setDefault() helper, but if it only sets a boolean, a race between two tabs can leave two defaults. Back it with a partial unique index or a DB::transaction + lockForUpdate().

Snapshot addresses onto orders. Never let a placed order read live from the address table. Copy the address fields (or store a JSON snapshot) onto the order at placement time. Delivery addresses mutate — customers move — and a mutable foreign key means historical orders silently rewrite themselves.

Form Request + package rules. Compose your StoreAddressRequest from the package's rules rather than duplicating regexes for postal codes and phone numbers. If 1.1.0 added or loosened a rule, you inherit the fix for free. If you need per-country variation, wrap the package rules in a Rule::when() based on the selected country rather than forking the rule class.

Morph relations for reuse. Address bundles typically attach polymorphically so the same table serves User, Order, and Warehouse. Lean on that instead of adding a second address table for billing — a type column plus a scope (billing(), shipping()) is the cheaper path.

API resources at the boundary. Don't return the raw model from controllers; the package model's toArray() will leak internal columns and change shape between minor versions. A dedicated AddressResource is your version buffer.

Seed country/region data via a dedicated seeder and cache it — the reference tables are read constantly at checkout and rewritten rarely. Cache::rememberForever() keyed on the table's max updated_at is usually enough.

Gotchas and Tips

• The 1.1.0 notes are a changelog link, not release notes. Run composer update tourze/delivery-address-bundle -W --dry-run first, then read the diff. Watch specifically for changed validation rules (existing garbage data may start failing), new non-nullable columns on a large table (locking migration), and changed config defaults.
• Published config is frozen. vendor:publish does not overwrite. After any minor bump, diff config/delivery-address.php in the package against yours; missing keys fall back to package defaults in some packages and throw in others.
• Migrations published vs. loaded. If the package loads migrations from database/migrations in the service provider, you cannot edit them without a fork. Decide early: publish and own them, or never touch them and add columns in your own migrations.
• Unique-default constraints. Application-level "only one default" logic is not enforced by the DB. Add the constraint if your database supports partial indexes; otherwise guard every write path, including admin panels and imports that bypass your service layer.
• Mass assignment. If you extend the model, the parent's $fillable may not include columns you add. Symptom is a silently-ignored attribute on create() — check $model->getChanges() when an update "doesn't stick."
• Country/state validation is the usual bug source. Postal code and phone rules are locale-specific; test with a deliberately awkward address (UK postcode, Japanese prefecture, an address with no state field) before shipping.
• Geocoding is a latency trap. If the package offers geocode-on-save, keep it in a queued job. Synchronous HTTP calls to a geocoder inside a form submission is the most common cause of checkout timeouts in address packages.
• Extension points to prefer: model binding in config, custom validation rules, and model events (saving, saved) on your subclass. Avoid decorating the package's repositories/services unless the container binding is documented — those internals move fastest between minor versions.
• Debugging tip: if addresses disappear or resolve to null on the relation, suspect a morph map mismatch (Relation::enforceMorphMap) or a type column value the package's scope doesn't expect. Log the raw row before blaming the relation.
• Pin with a caret and read changelogs on bumps: "tourze/delivery-address-bundle": "^1.1". Given the terse release notes, treat every minor as potentially behavioral and rely on your test suite around the checkout address flow as the real safety net.