Address Laravel Package

Getting Started

capell-app/address is the address/geo module for the Capell CMS family, so treat it as an add-on to a Capell install rather than a standalone package.

1. composer require capell-app/address (match your Capell core version — see Gotchas).
2. Publish and run its migrations: php artisan vendor:publish --tag=address-migrations (also check for address-config and address-assets tags via php artisan vendor:publish and pick from the list rather than guessing tags).
3. Read config/address.php first. It is the single best map of what is swappable: model bindings, table names, and any country/state data source.
4. Skim the package's src/Models and src/Http (or src/Crud) directories to see whether records are plain Eloquent or driven by Capell's CRUD layer — this determines how much you can customise without forking.

First real use case: seed countries/states, then attach an address to an existing model (User, Order, Company) and render a country/state/postal-code form. Get that loop working end-to-end before touching formatting or geocoding.

Implementation Patterns

Attach addresses via the provided relation, not a hand-rolled FK. The package exposes an addressable/polymorphic relationship (or a HasAddresses-style trait). Use it so the package's own queries, admin screens, and eager-loading helpers keep working. If you need multiple address types, model them as a type column value (billing, shipping) rather than a second table.

Model swapping over editing vendor code. Bind your own model in config/address.php (extend the package model, add scopes/accessors) instead of publishing and patching. This is the difference between a survivable upgrade and a rewrite at beta exit.

Form data as a service. Wrap country/state lookups in a small repository or cached selector (Cache::remember('address.countries', ...)) and expose one method the whole app uses for the country → state cascade. Do not let three different controllers each query the tables.

Validation as rules, not regexes. Postal codes and state requirements vary per country. Compose validation as a Rule object keyed by ISO country code; the package handles storage, not your business rules.

Admin CRUD belongs in Capell. If you're on Capell, register/manage addresses through the admin panel resource rather than building parallel screens — the package's admin integration is the reason to use it.

Formatting at the edge. Keep a single presenter/formatter (toArray, __toString, or a Blade component) for rendering an address block; store structured fields, assemble one-line/international formats only at output time.

Gotchas and Tips

• Pin the beta exactly. 1.1.0-beta.47 moved four betas with no described changes — that's a maintenance cadence, not a stability signal. Use an exact constraint ("capell-app/address": "1.1.0-beta.47") and budget for review on each bump, or require minimum-stability: beta with prefer-stable: true so you don't accidentally pull worse transitively.
• Release notes are a changelog link only. Read the compare diff (beta.43...beta.47) before upgrading; there is no prose to trust. Check migrations, config keys, and model class names in the diff specifically.
• Migration collisions. If the package loads migrations from src/ and you published them, you'll get duplicate-table errors. Pick one strategy and delete the other copy.
• Morph map. If you call Relation::enforceMorphMap(), the package's stored addressable_type values must be in your map, or existing rows silently stop resolving.
• ISO codes are the trap. Normalise to alpha-2 uppercase on write and read; mixed us/US/numeric codes will fragment your state lookups and produce empty dropdowns that look like a data bug.
• N+1 on listings. Address relations are cheap individually and expensive in lists — always with('address.country', 'address.state').
• Deletion semantics. Decide explicitly whether addresses are cascadeOnDelete, soft-deleted, or orphaned when the parent goes. The package default may not match your audit/retention requirements.
• Debugging empty selects usually means unseeded geo tables, not a broken component. Run the seeder and confirm row counts before digging into the form layer.
• Extension points to prefer: config model bindings → events/observers → decorating a bound service → subclassing. Forking the package is a last resort while pre-1.0-stable.
• Tests: RefreshDatabase plus the package seeder in setUp; assert against codes, never against translated country names.