Laravel Address Laravel Package

Product Decisions This Supports

• PH market entry, checkout localization, and KYC onboarding. Region → Province → City/Municipality → Barangay cascading selection is table stakes for Philippine e-commerce, logistics, lending/fintech, and government-adjacent services. The package ships the Eloquent models, migrations, and seeded PSGC geography, converting what is normally a multi-sprint data-sourcing and cleansing project into a configuration-and-integration task. That is a schedule and staffing decision, not just an engineering detail.
• Build vs. buy for address capture — the core tradeoff. It frames the choice cleanly: self-hosted, MIT-licensed dataset (zero marginal cost per lookup, no PII egress, no third-party data-processing review, no per-checkout billing) versus commercial providers (Google Places, HERE, Mapbox, Loqate) that add rooftop validation and geocoding but bill per transaction and add vendor and rate-limit risk. For a PH-focused product with meaningful order volume, per-lookup math usually decides this alone; the package makes the "build" side credible at a fraction of the cost.
• Enumerate vs. verify — write this distinction into the PRD. The package lets users select from a correct, canonical list. It does not confirm the address is real, deliverable, or geocodable. Stakeholders routinely conflate the two and over-scope toward a geocoding contract nobody budgeted for. Naming the boundary at requirements time prevents that drift.
• Data currency becomes a recurring line item, not a project. v13.0.0 ships an explicitly dated PSGC 1Q 2026 publication alongside Laravel 13 support — evidence of an upstream refresh cadence rather than a one-off dump. That reframes "we must own and maintain a Philippine address dataset" from a roadmap epic into "we must track upstream releases quarterly." Materially smaller scope and a cheaper headcount ask.
• Delivery success, re-attempt fees, and COD leakage. Barangay is the operational unit for PH couriers. Stale or malformed barangay data converts directly into failed deliveries, redelivery charges, and lost cash-on-delivery revenue. This informs decisions on delivery-fee zoning, courier integration readiness, and whether to invest in address quality before scaling order volume.
• KYC, compliance, and fraud. Standardized component codes improve identity matching, shrink manual review queues, and support BIR-compliant invoicing with a complete registered address on official receipts. Canonical region/province codes also make audit and reporting defensible — group demand, coverage, and expansion analysis on codes, never on name strings.
• Reversibility as a deliberate design decision. Wrapping the package behind an internal AddressResolver contract costs little now and turns a vendor bet into a swappable implementation detail. That determines whether a future pivot (to Google Places/Loqate, or in-house data) is a one-file swap or a re-architecture.
• Upgrade cadence and framework coupling as budget input. The major version tracks the Laravel major (v13 ↔ Laravel 13). Adopting the package means adopting its release train, with a small, predictable upgrade ticket each framework cycle — flag it in planning so it is never discovered mid-incident.

When to Consider This Package

Consider it when most of the following hold:

• The Philippines is a real or planned market, and you need structured address capture in checkout, signup, KYC, delivery, or field-service flows.
• You are on a supported Laravel version and already use Eloquent. Integration cost is then days, not weeks, and service-provider auto-discovery means no registration step.
• You need selection correctness, not rooftop precision. If "the customer picks the right barangay from a canonical list" satisfies the requirement, this is sufficient. If you need geocodes, deliverability scoring, or address cleansing of messy free text, that is a separate purchase.
• Your order and invoice volume makes per-lookup billing unattractive, or you have data-residency/PII constraints that make shipping addresses to a third-party geocoder a review burden.
• You can absorb a quarterly dataset review and a predictable framework-upgrade ticket. Budget both explicitly.
• You want a canonical key for reporting. Codes enable group-by-region demand analysis and courier zoning in a way free-text addresses never will.

Look elsewhere — or plan to buy — when:

• You are not operating in the Philippines. The bundled data is PH-specific; the generic "countries/states/cities" framing in the repo description should not be trusted over the migrations. Confirm the actual tables before designing against them.
• "Address validation" in your requirements means verification or geocoding. This enumerates a correct list; it does not confirm anyone lives there, that a courier can deliver, or where the pin lands.
• Multinational coverage is required. You need a global address stack, not a PH dataset.
• You are not on Laravel, or are pinned to an older major for framework reasons. The dataset refresh shipped coupled to the Laravel 13 bump in v13.0.0 — staying on v12.x for compatibility means staying on the older snapshot. Diff constraints and migrations before deciding whether the freshness is worth the framework jump.
• You need vendor SLAs, support contracts, or an actively maintained dataset with published commitments. This is a small, single-maintainer-style open-source package (41 stars, 0 dependents, MIT). Verify health, issue responsiveness, and bus factor against your risk appetite; the mitigation is the AddressResolver abstraction, not a support ticket.

Adoption defaults worth setting on day one: pin the version, put a quarterly "review yajra/laravel-address releases" item on the calendar, add a smoke test asserting row counts plus a handful of known codes, handle Metro Manila's nullable province step explicitly (~17 regions, ~82 provinces, ~1,600 cities/municipalities, ~42,000 barangays), and snapshot human-readable names alongside codes at write time so a re-seed never silently rewrites an issued invoice.

How to Pitch It (Stakeholders)

To executives (one paragraph): Entering the Philippine market requires customers to pick a region, province, city or municipality, and barangay — and getting that wrong costs real money in failed deliveries, redelivery fees, and lost COD revenue, while also undermining KYC and BIR-compliant invoicing. Buying this capability from a commercial geocoder means per-lookup billing and sending customer addresses to a third party. This MIT-licensed Laravel package supplies the full official PSGC geography, self-hosted, at zero marginal cost per lookup, with a publisher that refreshes the dataset on a dated cadence (the current release ships the 1Q 2026 publication). The realistic ask is a few days of integration plus a small recurring maintenance line — quarterly dataset review and a framework upgrade ticket — rather than a data-sourcing project. One limit to set expectations on: this makes address selection correct and structurally validated; it does not verify that an address is deliverable or geocodable.

To engineering (the ask): Integrate it behind a thin AddressResolver interface from day one — regions/provinces/cities/barangays plus validateChain() — with an Eloquent implementation bound today. That single decision keeps a future swap to Google Places/Loqate, or to an in-house dataset, to a one-file change, and lets tests run against a trimmed fixture instead of 42k rows. Non-negotiables for the first release: ship the cached cascading picker end-to-end before anything else; validate the chain server-side by resolving the leaf and deriving ancestors rather than trusting client-supplied parents; store codes as foreign keys and snapshot names for historical records; refresh data via idempotent upsert keyed on code, never truncate; treat province_code as nullable for NCR and independent cities; verify the shipped migrations actually index province_code/city_code/searchable name at 42k rows; and add a smoke test on row counts plus known codes. Use the configurable model bindings as the extension point for geocoordinates or an active flag — do not fork. Track the package's major version against ours; assume a small upgrade task each Laravel cycle, and pin the version so a dataset change is a deliberate decision rather than a surprise in a routine composer update.