Filament Thailand Location Picker Laravel Package

Technical Evaluation

Architecture fit

• Filament-native form field plugin (ProvinceSelect, DistrictSelect, SubdistrictSelect, zip code, plus Region/Geo) that slots directly into an existing Filament panel form schema — no new service, no frontend build step, no separate address microservice.
• Ships a static, bundled Thai administrative dataset (Region → Province → District → Subdistrict → Zip Code). This is the single most important architectural property: zero runtime dependency on a government or third-party API, so it works in air-gapped, on-prem, and low-connectivity deployments, and carries no per-request cost or quota.
• The trade-off is that it is an opinionated, single-country component, not a general address abstraction. If the roadmap ever includes multi-country address capture, this package will need to be wrapped behind our own field/interface rather than used directly in form schemas.

Integration feasibility

• Composer install + plugin registration in the PanelProvider + adding fields to the schema. Additive and low-ceremony.
• v1.1.0 is entirely additive: an enable_geo toggle (global config plus per-field ->geoEnabled(false)) and publishable en/th JSON translation files. Nothing in the release notes suggests a breaking change, and no existing API is removed or renamed.
• Real integration effort sits in the data model decision (what we persist: codes vs. name_th/name_en), not in wiring the fields.

Technical risk

• Dual locale mechanism — the top risk introduced by this release. UI labels now follow App::getLocale(), while the data columns follow the separate thailand-plugin.locale config. These can diverge, producing English labels over Thai province names (or the reverse) in the same form. This needs an explicit team convention and a test case, or it will surface as a UI defect.
• enable_geo default is undocumented in the notes. If the default is true, the release is backward compatible. If false, existing forms silently lose the Region selector and any cascaded filtering that depended on it. Must be verified before upgrading.
• Static dataset freshness. Thai administrative boundaries do change; the package must be upgraded to get corrections. There is no self-service data refresh, and no stated provenance (e.g., DOPA) or refresh cadence in the notes.
• Vendor concentration. Small, single-maintainer package in a niche domain. Bus-factor and abandonment risk are real, mitigated by the fact that the failure mode is graceful (fork + own the dataset).
• Verification matrix expands. Locale (en/th/other) × geo mode (on/off/global/per-field) × field requiredness is now a 2×3+ test surface for every form we build.

Key questions

• Which Filament major versions and Laravel/PHP ranges are supported, and is there a stated upgrade policy for Filament v4?
• What is the default value of enable_geo on upgrade — does it preserve existing behavior?
• Does disabling geo persist a region value, omit the field entirely, or leave stale data in the region column?
• Does the package expose stable numeric codes (not just names) for province/district/subdistrict, so we can key reporting and downstream integrations off codes?
• How are required/conditional validation rules expressed per field, and do they hold when geo is disabled?
• Is the dataset replaceable/overridable, or do we depend entirely on upstream releases for corrections?
• What are the translation fallback semantics when App::getLocale() returns a value other than en/th (e.g., th_TH, ja)?

Integration Approach

Stack fit

• Standard Laravel + Filament + Livewire stack; no Node build, no JS asset pipeline, no migrations against our own database unless we choose to normalize address data. Behaviour is config-driven (Laravel config + JSON lang files), which is idiomatic for the stack and easy to reason about in code review.
• Cascading selects rely on Livewire round-trips; acceptable for admin-panel usage, which is the expected context.

Migration path

• Greenfield panels: straightforward — install, register, publish config and translations into the repo, add fields.
• Brownfield (free-text address fields or a hand-rolled cascading select): the hard part is backfilling legacy text into structured values. Plan a mapping exercise from existing strings to district/subdistrict codes, expect a manual-review tail for ambiguous entries, and keep legacy columns in place during the transition so reports don't break.
• Decide up front whether we store codes or names. Names are display-friendly but break when the dataset updates or when locale conventions change; codes are stable and should be the system of record, with names rendered at display time.

Compatibility

• Translation files use Laravel's JSON lang convention (lang/vendor/thailand-plugin/{en,th}.json) — supported by any current Laravel version.
• Because translations are now publishable, we own the copies in our repo; they will not auto-update with upstream releases. That is a feature for customization and a maintenance obligation for typo fixes.
• Watch for locale-format mismatch: App::getLocale() will typically return en or th here, but any th_TH-style configuration will miss the lookup and fall back.

Sequencing

1. Spike in a sandbox panel: confirm Filament version compatibility and the actual default of enable_geo.
2. Pin and publish — lock the version, publish config and translations into the repository, commit them so config drift is visible in diffs.
3. Decide the data model (codes vs. names) and the locale convention (whether the UI locale and the data-column locale are deliberately locked together).
4. Set geo policy per form; prefer per-field ->geoEnabled(false) over the global switch unless the whole application genuinely doesn't need Region.
5. Backfill legacy data with a reconciliation report before switching the UI over.
6. Test matrix across locale × geo mode, plus a config:cache run in CI.
7. Roll out panel by panel behind a feature flag rather than globally in one deploy.

Operational Impact

Maintenance

• Low ongoing code footprint — the maintenance load is governance, not code: tracking upstream releases (especially dataset corrections), owning the published translation overrides, and re-validating after each Filament major upgrade.
• The new dual-locale configuration is permanent configuration debt. Document the two knobs and their intended relationship in the repo, or new team members will set one and not the other.

Support

• Expect a class of tickets we did not have before: "the labels are in English but the provinces are in Thai." Build a short runbook mapping symptom to config key.
• Flipping enable_geo globally is a visible, application-wide UX change. Treat it as a product decision with a changelog entry, not a config tweak.
• Thai-language copy should be signed off by a native speaker before the translations are frozen into our repo.

Scaling

• No external API means no latency, quota, rate-limit, or availability surface — the package scales with the application, not with a vendor.
• Option-set sizes are modest (roughly 77 provinces, high hundreds of districts), so Livewire payloads are not a concern for typical forms. The risk is form-level, not system-level: many cascading fields on one large form multiply round-trips per user interaction.
• Storage scales trivially whether we persist codes or names; the cost difference is in reporting correctness, not performance.

Failure modes

• Missing translation key → raw key string rendered in the UI (e.g., thailand-plugin.province); caught only if someone inspects the form in the affected locale.
• Locale not matching en/th → unverified fallback behaviour; could show English in a Thai-only deployment.
• Stale dataset → users select a district/subdistrict that no longer matches reality; downstream Thai systems (shipping, tax, identity verification) may reject the address, and the error surfaces far from the cause.
• config:cache not cleared after changing enable_geo → change appears not to apply, generating a spurious bug report.
• Re-publishing translations on upgrade silently overwrites our customizations unless we diff before publishing.
• Upstream abandonment → we fork and own the dataset; recoverable, but should be an explicit contingency given the small vendor.

Ramp-up

• Roughly half a day for a Laravel/Filament-fluent engineer to get fields rendering in a panel; 1–2 days including the data-model decision and the locale × geo test matrix.
• Add ~1 day of Thai-language review and product sign-off for the published translations.
• Brownfield data backfill is the schedule variable — size it from the actual volume of legacy address records rather than from the package's complexity.