Laravel Address Laravel Package

Technical Evaluation

Architecture fit. Eloquent-native, which is the whole point: the package ships models, migrations, seeders, and a morphed Address relation that attaches to any entity, so it slots into an existing Laravel domain model without a new service or datastore. Config-driven table names and model bindings (config/address.php) make it an extension point rather than a fork target — we can add delivery_zone_id, geocoordinates, or an active flag on our own subclasses and repoint config. The surface area is small and the dependency footprint is Laravel-only, so there is no architectural argument against it; the argument is entirely about data stewardship and version coupling.

Integration feasibility. Days, not weeks, for a team already on Eloquent: composer require yajra/laravel-address:^13.0, auto-discovery, publish config + migrations + seeders, migrate, seed. The real effort is not the install — it is the write-path decision (store canonical codes and snapshot human-readable names into denormalized columns), the AddressResolver contract, and legacy free-text backfill if we already hold addresses. Plan for the install to be a half-day and the surrounding correctness work to be the sprint.

Technical risk.

Key questions to close before committing.

1. Schema truth: do the shipped migrations persist PSGC codes alongside names, what are the FKs, and are they actually indexed?
2. Nullability: is province_code nullable and is the chain Region → Province → City/Municipality → Barangay strict or lenient?
3. Dataset provenance and terms: which PSGC publication is bundled, and is attribution expected or required?
4. Release policy: is the PSGC refresh guaranteed on a cadence, or opportunistic? Is a data-only refresh ever shipped outside a major?
5. Seeder profile: wall-clock time, peak memory, and DB size at ~42k barangays — needed to size deploy and CI budgets.
6. Support posture: is there any commitment to supporting current Laravel majors promptly, or do we accept lag?
7. Real table set: are regions/provinces/barangays present, or is the "countries/states" description real?

Integration Approach

Stack fit. Laravel 12/13 with Eloquent and PHP 8.5 is the tested matrix. If we are not on a supported Laravel major, the conversation ends — there is no framework-agnostic fallback, and the dataset is not separately consumable. Confirmed fit is essentially a prerequisite, not an evaluation criterion.

Compatibility and pinning. Match the package major to the Laravel major before running composer: ^13.0 ↔ Laravel 13 with the 1Q 2026 PSGC; v12.x ↔ Laravel 12 with an older snapshot. Decide this as a joint framework/data decision, not two separate ones — a framework pin silently pins geography. Pin exactly in composer.json and record the bundled PSGC release in the README next to the dependency.

Migration path.

• Greenfield (new address capture): no backfill. Ship the cascade picker end-to-end first, with write-time name snapshotting.
• Existing free text: do not attempt a big-bang migration. Match barangay → city → province in descending confidence, batch it, and route anything under threshold to manual review. Keep the legacy columns live behind a feature flag until parity is measured. Barangay fuzzy matching is genuinely hard — duplicates and near-identical spellings are common, and an over-eager match is worse than a null.
• Reference data refreshes: idempotent upsert keyed on code — never truncate. Retire discontinued codes with retired_at/active rather than deleting, so historical orders still resolve.

Sequencing (recommended).

1. Spike on a scratch connection. Publish config + migrations together, migrate, seed, and measure time/memory/DB size with DB::disableQueryLog(). Inspect actual schema and indexes. (~2–3 days; produces the answers to most key questions.)
2. Contract first. Define AddressResolver (regions, provinces, cities, barangays, validateChain) and bind an Eloquent implementation. This is the hedge against stale data, maintainer risk, and any future pivot to Google Places/Loqate.
3. Cascade checkout picker, behind a cache keyed by dataset version, with server-side chain validation on submit — resolve the barangay once, derive ancestors server-side, and ignore client-claimed parents.
4. Write path: persist codes as FKs and snapshot names into denormalized columns at write time. This is the single most important day-to-day decision; invoices and delivery manifests must not silently change spelling on a re-seed.
5. Index and caching hardening: add any missing FK/name indexes in our own migration; tier caches (regions/provinces ~day or process lifetime, cities ~hours, barangays per-city on demand), all keyed by dataset version.
6. Backfill behind a feature flag, then reporting/analytics grouped by region_code/province_code — never by name strings.
7. Test fixtures: export a handful of geography branches; seed those in CI, never the full 42k.

Operational Impact

Maintenance. Two recurring line items, both small and predictable, neither of which exists unless we create it: (a) a quarterly "review upstream release" task to catch PSGC publications and decide on adoption; (b) a per-framework-cycle upgrade ticket, since the major tracks Laravel's. Add a smoke test asserting row counts and a handful of known codes so a silent data regression fails CI rather than a customer's delivery.

Support. MIT, community-only, no SLA, single maintainer. We own the failure. Practical mitigation: keep the package behind AddressResolver, keep customizations in subclasses via config bindings rather than forking, and keep a documented fallback plan (a static PSGC import into our own tables) so a maintainer hiatus is an inconvenience rather than an incident.

Scaling. Read-mostly reference data; ~42k barangays is trivial for any relational DB and will not be the scaling bottleneck. The real scaling costs are elsewhere:

• Deploy/CI cost: a row-by-row seeder is fine locally and a liability in production deploy or CI. Prefer bulk upsert, and never seed the full dataset in test suites.
• Cache correctness: cache entries must be keyed by dataset version or a refresh serves stale lists indefinitely — a silent, confusing class of bug.
• Query shape: Barangay::with('city.province.region') across a page is fine; inside a loop it is not. Resolve codes once, reuse.

Failure modes to design against.

Ramp-up. Low for any Laravel developer — hours to productive, given models and migrations are provided. The non-obvious learning is domain, not code: PSGC hierarchy quirks, the city/municipality conflation, and the discipline of codes-plus-snapshot. Budget a short domain briefing for whoever owns the checkout and fulfillment paths, because that person — not the integrator — will be answering "why did this address change?" six months from now.

Bottom line. Cheap to adopt, cheap to reverse if wrapped properly, and it converts a multi-sprint data-sourcing and cleansing project into a configuration task — which is the actual product value here. The risks are concentrated in data currency and single-maintainer dependency, both manageable with a version pin, a quarterly calendar item, and the resolver contract. The deal-breaker conditions are narrow: not on a supported Laravel major, or a requirement for rooftop-level address verification.