Postal Codes Laravel Package

Technical Evaluation

Architecture fit. awcodes/postal-codes is not a service and not a validator-as-a-service — it is a reference-data provider wrapped in a Laravel package: a service provider, publishable config, migration, Eloquent model, and a GeoNames TSV import path. There is no runtime call to GeoNames in production. That means it fits as an internal data layer inside the Laravel app (or behind a small internal API), not as a third-party integration in the architecture diagram. The correct architectural shape is a repository interface owned by our domain, with the package confined to one adapter class. If we adopt it any other way — controllers and form requests touching the model directly — we inherit the lock-in without the low-cost exit that MIT and a small surface area otherwise give us.

Strategically this package reframes a build-vs-buy decision: own a dataset instead of pay per lookup. It buys self-hosting, zero per-lookup cost, no customer data leaving our VPC, and no new DPA. It does not buy deliverability confidence, rooftop geocoding, or anyone's uptime SLA. That trade needs an explicit product owner decision, not an engineering one.

Integration feasibility. Code-level integration is genuinely small: composer require, publish config and migrations, migrate, run the import command for one country. The cost is not in the package — it is in the data operations we now own: import pipeline, refresh cadence, schema verification per driver, normalization policy, and attribution compliance. Realistic sizing:

Technical risk.

• Maintainer concentration. Five stars, zero dependents, single maintainer — this is a bus-factor-one dependency. MIT and a small public surface make fork-or-vendor a genuinely cheap exit, but only if we've done the adapter isolation first. Adoption math: low risk on the code, real risk on the roadmap.
• Transitive framework pin — the sharpest governance issue. maatwebsite/excel ^4.0 requires illuminate/support ^12.0 || ^13.0. A postal-code lookup table therefore sets our Laravel floor at 12/13. Any Laravel 10 or 11 app cannot install it at all. This is the kind of constraint that surfaces three sprints into a platform upgrade and should be raised in the architecture review, not discovered in a PR.
• Correctness risk the test suite cannot catch. v1.0.2 fixed a real precision defect: Laravel 11 narrowed Blueprint::float() to float($column, $precision = 53), so the package's float('lat', 10, 8) silently produced a 4-byte single-precision column on MySQL, PostgreSQL, and SQL Server. Coordinates like 40.71277800 were rounded at write time. The suite runs on SQLite, which stores a full double regardless — so green tests prove nothing about schema on the production driver. This is a process risk as much as a code risk: we need a DDL assertion against a real driver in CI, or "tests pass" becomes a false signal in release reviews.
• The upgrade is a data operation, not a version bump. Moving from v1.0.1 to v1.0.2 corrects the schema for new installs only. Existing tables keep narrow columns, and values already written were rounded at insert. Recovery requires widening the columns and re-importing the source data — an ALTER alone restores nothing. If we ever ship v1.0.1, we owe the business a data remediation plan.
• Coverage and freshness are our problem. GeoNames coverage varies by country; Ireland, Hong Kong, and the UAE do not use postal codes at all. A hard validation rule that rejects empty input will block legitimate checkouts in those markets.
• Licensing. GeoNames data is CC BY 4.0 and requires attribution. That obligation flows to a product surface — about page, docs, API metadata — and needs legal sign-off before the first production import, not after.

Key questions to resolve before commitment.

1. Is postal-code lookup a product capability (we intend to invest and own the dataset) or a convenience (validate format, move on)? The answer changes everything downstream.
2. Which markets are in scope for the first year, and does each actually use postal codes?
3. What is our Laravel version posture? If any part of the estate is still on 10/11, this package is not installable there — full stop.
4. Do we treat postal code + country as personal data under our privacy review? (A "yes" strengthens the self-hosted case considerably.)
5. Are we prepared to own a quarterly refresh runbook indefinitely, with a named owner and an on-call path?
6. Is the near-term requirement format validation, region/tax resolution, or proximity search? These have very different accuracy bars — centroids are fine for depot/zone assignment and distance sorting, and not fine for anything a customer reads as "we know where you are."
7. Who signs off on CC BY 4.0 attribution placement?
8. Do we have a real-driver schema check in CI today, or would this be the first?

Integration Approach

Stack fit. Laravel 12 or 13 only, on PHP matching those floors, with MySQL, PostgreSQL, SQL Server, or SQLite behind it. The driver matters — coordinate precision behavior differs, and SQLite will mask schema defects that MySQL and PostgreSQL will not. If our production driver is MySQL or PostgreSQL, the spike must verify DDL there, not locally.

Migration path. Two distinct scenarios with different costs:

• Greenfield address feature — install, import one market, ship. Low friction.
• Retrofitting an existing address table — we must add a normalized column, backfill existing customer rows through a country-aware normalizer, index it, and accept that historical rows will have inconsistent normalization until touched. Budget this explicitly; it is usually where the estimate surprises.

Separately, if we ever run v1.0.1, the v1.0.2 upgrade is a planned data migration (widen + re-import), owned by whoever owns the data pipeline, scheduled like a schema change with a verification step.

Compatibility. Two hard constraints to check across the whole monorepo before sequencing anything:

1. Framework floor — maatwebsite/excel ^4.0 → illuminate/support ^12.0 || ^13.0. This is the gating constraint, and it comes from the spreadsheet library rather than the package itself. A lookup table pulling in an Excel library is heavier than "lightweight provider" suggests; note it in the dependency review.
2. Composer resolution — run a dry-run against every app that would consume it, not just the pilot.

Sequencing. Six stages, each with a gate:

1. Spike (timeboxed, 1 day). Install, publish, migrate, import a single small country (Netherlands is a good probe — it exercises the internal-space normalization path). Gate: SHOW CREATE TABLE / information_schema confirms double / double precision for lat/lng on the production driver.
2. Contract definition. Define PostalCodeRepository and our own PostalCodeData DTO. Package import stays inside one adapter. Gate: no package class names appear in controllers, form requests, or Blade.
3. Pilot market, end-to-end. Checkout postal-code capture with the soft-fail split: format validation may reject; dataset lookup never rejects. Gate: a deliberately-missing code completes checkout and logs, rather than blocking.
4. Import pipeline hardening. Chunked raw inserts (1k–5k rows), bypassing Eloquent, in a transaction or staging-table swap, run as a queued job. Gate: an interrupted import leaves no half-populated country in production.
5. Refresh job. Scheduled monthly/quarterly download → import to staging → row-count comparison against the previous run → swap. Record the GeoNames file date so we can answer "how current is our data" during an incident. Gate: one successful dry run and a documented rollback.
6. Market expansion. Adding a market becomes a repeatable runbook step (~2 days each), not a schema event. Gate: miss-rate instrumentation live per country before the second market ships.

Non-negotiable design decisions to lock in stage 1–3, not later:

• Store both postal_code (as published/typed) and postal_code_normalized (uppercased, separators stripped), and index the normalized column. Never store a postal code as an integer — leading zeros in 01234 vanish silently.
• Always query by (country_code, postal_code). One code can map to many rows; a silent first() is a well-known source of wrong-region bugs. Decide up front whether the feature takes the first row or returns a list.
• Cache lookups including misses, keyed by an import version or timestamp so a refresh invalidates automatically. Without negative caching, a bot probing random codes pins the database.

Operational Impact

Maintenance — we own data freshness; the package does not. The recurring obligations are concrete and must have a named owner:

• Quarterly (or monthly) GeoNames refresh with staging verification and row-count guardrail.
• Version/date record of the imported dataset, surfaced in an internal status view.
• Attribution maintenance on the product surface (about page, docs, API metadata) — a legal obligation, not a nicety.
• Pinned version (^1.0.2), reviewed on a cadence, with the fork/vendor path kept warm.

Support. No vendor SLA. Support is a GitHub issue tracker with one maintainer. That is acceptable only because the surface is small and MIT: if the maintainer disappears, we can vendor the code and continue. The mitigation is organizational — the adapter interface and our own DTO must exist before we depend on this in a revenue path, not after. Budget roughly a day a quarter for dependency and upstream review.

Scaling. Three levers, in order:

1. Index discipline — composite index on (country_code, postal_code_normalized); without it, every lookup is a scan.
2. Cache-first reads with negative caching. These mappings are immutable between imports, which makes them ideal cache entries and the single highest-leverage scaling decision.
3. Import by market, never worldwide. Per-country files range from a few thousand to tens of thousands of rows; a global load dominates import time, table size, and index tuning for a product that serves three countries.

For proximity, a naive haversine is a full table scan. Prefilter with a bounding box (± radius/111 for latitude, adjusted by cos(lat) for longitude), then filter by great-circle distance. With v1.0.2's double precision this is defensible for zone assignment and distance sorting — and still city-level centroids, not rooftop.

Failure modes and their blast radius.

The single most important operational control is the miss-rate metric per country. A climbing miss rate in a supported market is our earliest signal that coverage is thin or an import slice is wrong — and it is the number that decides keep-versus-replace in a future build-vs-buy review. Instrument it before the pilot exits, not after expansion.

Ramp-up. One backend engineer, roughly 2–3 weeks elapsed to production for the first market including the adapter, pipeline, refresh job, and fixtures. Each additional market is ~2 days of runbook execution. The learning curve is not in the package — it is in the data operations discipline and in the normalization rules per country (Canada and the UK use an internal space; the Netherlands uses 1234 AB; Germany has none).

Recommendation. Proceed to a one-day spike, contingent on three things being true: (1) the estate is on Laravel 12/13 or will be, (2) legal signs off on CC BY 4.0 attribution placement, and (3) we accept ownership of a quarterly refresh runbook with a named owner. Kill criteria at the spike gate: narrow-float schema that cannot be corrected on our driver, or a pilot market whose miss rate makes the dataset unusable for the intended product surface. Treat this as a narrowly-scoped capability behind an interface, not a strategic platform bet — the exit is cheap, and we should keep it cheap.