Postal Codes Laravel Package

Product Decisions This Supports

• Build vs. buy for address validation. This package turns a vendor decision into a data-ownership decision. Paid APIs (Smarty, Lob, Google Address Validation, Melissa) sell deliverability confidence, rooftop geocoding, and an uptime SLA. GeoNames sells none of those — but it costs nothing per lookup, runs inside your infrastructure, and keeps postal code + country out of a third party's hands. If privacy review treats address fragments as personal data, self-hosting removes a data processing agreement from the critical path. Frame the fork as validation confidence vs. vendor dependency.
• Checkout and registration UX — the soft-fail principle. The most valuable decision here is architectural: separate format validation (does this look like a Dutch postal code? — may fail the form) from dataset lookup (do we recognize it? — never fail the form). Conflating them is how paying customers get blocked because a rural code is missing from a quarterly dump. The package supports the correct pattern; the decision to enforce it is ours.
• Roadmap scoping for "geo" epics. Most requests labelled "geocoding" are really region, tax-zone, depot, or shipping-zone assignment. A self-hosted centroid table answers those. That distinction lets us cut a large geocoding epic down to a lookup table plus an import job, and reserve vendor spend for features that genuinely need rooftop accuracy.
• Market expansion as an explicit config decision. Postal codes are not universal — Ireland, Hong Kong, and the UAE don't use them. The package forces a per-market call on whether the field is required, optional, or absent, which is a product decision surfaced early rather than a support ticket after launch.
• Data ownership as a standing commitment. Adopting this creates a recurring workstream: scheduled GeoNames refresh, import versioning, miss-rate monitoring per market. That is a roadmap line item and an on-call consideration — not a one-time install. Budget for it before committing.
• Upgrade sequencing. The package is Laravel 12/13 only (a transitive constraint from maatwebsite/excel ^4.0). If we're on 10 or 11, adoption is coupled to a framework upgrade and should be planned as one.

When to Consider This Package

Adopt when most of these hold:

• The app is on Laravel 12 or 13 and there's no appetite to fight the transitive framework floor.
• We serve a known, small set of markets where GeoNames coverage is adequate, and we can live with quarterly-ish freshness.
• The job is postal-code existence, normalization, and region/centroid lookup — not deliverability, not rooftop precision.
• Privacy or legal prefers self-hosting, or per-lookup vendor pricing is painful at our volume, or lookups happen in bulk (imports, batch enrichment) where per-call fees compound.
• Someone will own the refresh job and the miss-rate metric. A stale dataset is worse than no dataset, because it looks authoritative.
• We're comfortable pinning ^1.0.2 and hiding the package behind our own repository interface and DTO.

Look elsewhere when:

• We need deliverability confirmation, address correction, or rooftop geocoding — buy a vendor. This package complements those; it does not replace them.
• We need global coverage on day one, or markets where GeoNames is thin.
• A vendor SLA and named support contact are hard requirements. Five stars, zero dependents, one maintainer is real risk, and the v1.0.2 fix — while a good signal about the maintainer — doesn't change the adoption math.
• The team won't fund ongoing data freshness. Prefer a vendor who owns that problem.
• The app is on Laravel 11 or earlier.

How to Pitch It (Stakeholders)

For executives. A small, MIT-licensed Laravel package that installs a self-hosted postal-code dataset from GeoNames. It replaces per-lookup address APIs for one narrow but common job: "is this a plausible postal code, and roughly what region is it in?" Zero marginal cost per lookup, no customer address data leaving our infrastructure, no vendor contract or DPA. Be equally clear about what it is not: it is not an address validator or a geocoder, it carries no SLA, and data freshness becomes our responsibility. The ask is a timeboxed spike on one market, plus sign-off on CC BY 4.0 attribution (which must appear on an about page, docs, or API metadata) and ownership of the refresh job.

For engineering. It publishes a config, a migration, an Eloquent model, and an import command for GeoNames TSV exports — no runtime dependency on GeoNames. Three constraints to internalize: the framework floor is Laravel 12/13 via maatwebsite/excel ^4.0; pin ^1.0.2, and treat upgrading an existing install as a re-import, not an ALTER, because pre-1.0.2 coordinates were rounded at insert time on MySQL, PostgreSQL, and SQL Server; and isolate the package behind a repository interface returning our own DTO, given the maintainer and dependency profile. Validate the generated DDL on the production driver — the test suite runs on SQLite, which cannot catch the float-precision class of bug.

Decision gate. If the requirement turns out to be deliverability or rooftop accuracy, this package is a complement to a vendor, not a substitute. Resolve that question before the spike, not after.