soap/thai-addresses
Laravel package providing complete Thai address data — provinces, districts, subdistricts, and postal codes — with seeders, models, and lookup helpers. Easily import and query hierarchical Thai geographic data for forms, validation, and address autocomplete in PHP apps.
Architecture fit. The package is a Laravel service provider that publishes config, migrations, models (Province, District/Amphure, Subdistrict/Tambon) and a seeder for ~77 provinces, ~900 districts, and 7,000+ subdistricts plus postal codes. That is a "reference data as a first-class domain" pattern: the hierarchy lives in real tables with real foreign keys, which our own addresses table can constrain against. This sits comfortably in a conventional Laravel monolith or modular monolith. It is a poor fit as a core primitive in a multi-country architecture — a Thailand-only package at the center of the address schema creates a fork-in-the-road the moment a second market appears. The correct architectural framing is "country data pack behind our own address abstraction," not "our address model is the package's model."
Integration feasibility. Low friction. Composer install, vendor:publish, migrate, db:seed. The bundle includes optional API routes (/api/provinces, /api/districts/{id}, /api/subdistricts/{id}) for prototyping cascading dropdowns, and Eloquent relations for server-side forms. The realistic day-one scope — province → district → subdistrict cascade with postal code derived from the selected subdistrict — is a few days of work, not a project. The material integration cost is not the install; it is the follow-on migration for indexes on province_id/district_id/postal_code, which the package reportedly ships without, and the validation layer we must write ourselves (district belongs to province, subdistrict belongs to district — never trust the client cascade).
Technical risk. Four things a TPM should carry on the risk register:
@soap), and the release history is mostly Dependabot noise. If the maintainer goes quiet, we own the data.provinces/districts/subdistricts, we must rename in config before migrating; and vendor:publish --force will overwrite edited migrations, so package migrations must be treated as read-only with our indexes added in our own migrations.Key questions. (1) What is the dataset's provenance and update cadence — is there a documented source and version stamp? (2) Does the data licence permit commercial redistribution and internal mirroring? (3) Is the schema stable enough to foreign-key against, or should we own an addresses table that stores subdistrict_id plus a snapshot of the postal code? (4) Is Thailand first-market-only for the foreseeable horizon, or the first of several — this determines whether we build an abstraction now or defer? (5) Do we need geo capability (lat/long, polygons, reverse geocoding)? If yes, this is a data source at best and we need a separate provider.
Stack fit. Native Laravel: service provider, config, migrations, seeders, Eloquent models, optional routes. It drops into an existing Laravel app with no new runtime dependency beyond the package itself — no queue worker, no external service, no credentials. That matters: it is a data dependency, not an infrastructure dependency, so it doesn't expand our operational surface area.
Migration path. Sequence it as: install and publish into a scratch branch → rename tables in config/thai-addresses.php if we collide with existing schema → run migrate + seeder in staging → verify row counts and spot-check known postal codes → add our own follow-up migration for indexes and any additional FKs → write server-side chain validation → wire the cascade into the form. The seeder is thousands of rows: wrap in a transaction, disable FK checks during seeding, and expect to raise max_execution_time on constrained hosting. Our address table should store the foreign keys and a denormalized postal_code column so invoices printed historically don't change if the dataset is later re-seeded.
Compatibility. Requires the Laravel/PHP version matrix to match ours — unverified from the materials and should be confirmed before scoping. v3.1.1 → v3.2.0 is semver-minor with no signalled breaking API or schema changes, so treat it as a drop-in upgrade. We pin the version regardless. If we layer custom data on top of the seed files, diff before re-seeding to avoid clobbering local edits.
Sequencing. This belongs in the "enable Thailand" epic, ahead of checkout/shipping/invoicing work, not in a generic dependency backlog — the data-model commitment (IDs, codes, hierarchy) is semi-permanent, and bolting it on after custom address tables exist incurs a migration tax. Suggested order: decide the address abstraction (Thailand-only vs. country-agnostic shell) → adopt the package behind it → build the cascade and validation → add indexes → then layer shipping/tax/invoice logic on top. Feature work that follows from the same foundation: address autocomplete and validation, shipping-zone and courier-rate logic, store locator and coverage maps, VAT/tax address capture, invoice and fulfilment formatting.
Testing. Do not run the full seeder in CI — it will dominate suite runtime. Seed a small fixture subset and assert our cascade validation and postal-code resolution logic, not the package's data.
Maintenance. Modest but non-zero, and it is entirely about the data rather than the code. Provinces and districts change rarely and can be cached for a day or longer; subdistricts are larger but still static reference data. Two ongoing obligations: keeping our index migration in sync when package migrations change, and periodically re-seeding to pick up boundary changes. Because the package's release notes don't describe dataset changes, plan to diff seed files between versions and decide on data merit rather than semver alone.
Support. In-house knowledge required is shallow — any Laravel developer can read the config and models. The real support risk is external: no vendor, no SLA, single maintainer. If Thai addresses become commercially critical (they will, the moment invoicing or shipping depends on them), mirror the seed data into our own repo and treat the package as a bootstrap rather than a live dependency. That converts a bus-factor risk into a routine data-refresh task we control.
Scaling. Read-side, this is trivial: three small-to-medium reference tables, cacheable, with predictable access patterns (cascading selects hit province_id and district_id; lookups hit postal_code). The only genuine scaling concern is the missing indexes — without them, cascading-dropdown queries will scan, and that degrades quietly under load. Fix it in our own migration on day one. Write-side, nothing here scales with user volume; the tables grow only when the government reorganizes.
Failure modes. (1) Stale data — a boundary change means our cascade offers a subdistrict that no longer exists or omits a new one; silent and hard to notice without a data-vintage check. (2) Schema collision — publishing into a database that already has provinces/districts and discovering it during deploy. (3) Seeder timeout on shared or constrained hosting, leaving a partially populated table. (4) Dual route registration — the package's /api/* routes enabled alongside our own controllers causes confusing duplicate-route errors; disable them in production. (5) Postal-code assumptions — computing the zip from the subdistrict instead of reading it, producing wrong invoices for the minority of edge-case tambons. (6) Package abandonment — no upstream fix if a Laravel major version breaks compatibility.
Ramp-up. Very low for engineering: half a day to read config and models, a day to have staging seeded and the cascade working. The ramp-up cost that matters is organizational — product and finance need to agree that Thai address data is reference data we adopt and version, not something we curate. Before shipping compliance-adjacent features, ask the maintainer (or check the repo) how dataset changes are tracked, confirm the data licence supports commercial use, and record the data vintage we are shipping. Pin to v3.2.0, run the seeder in staging, spot-check known postal codes, and diff against v3.1.1 to establish whether the dataset actually changed — if it did, that is the reason to upgrade; if not, upgrading is optional hygiene.
How can I help you explore Laravel packages today?