Filament Locationpickr Field Laravel Package

Technical Evaluation

Architecture fit

• The package is a Filament form field: a thin UI component that renders a Google Maps picker and writes coordinates into form state. It sits entirely in the presentation layer of a TALL-stack admin panel — no migrations, no models, no service provider magic beyond asset registration.
• This is a good architectural shape for the problem. Geospatial capture is an admin-side data-entry concern; it should not leak into domain models. If we persist latitude/longitude (and optionally a formatted address) in ordinary decimal columns, the field becomes a swappable detail rather than a load-bearing dependency.
• Fit is conditional on us already running Filament. If we are on Nova, plain Blade, or a custom Livewire admin, the package has no value and the effort should go into a standalone Alpine component instead.
• The hard external dependency is not the package — it is the Google Maps JavaScript API: an API key, a billing account, key restriction policy, and a client-side script loaded from Google's CDN. That is a platform commitment, not a package decision.

Integration feasibility

• Straightforward for a developer already fluent in Filament v3. Realistic path: composer require, publish/register the field's assets, supply the Maps API key via config/env, drop the field into one resource form, persist the returned state.
• Estimated effort: 0.5 day spike to confirm version compatibility and the shape of the field's state, 1–3 days to integrate, validate, harden, and document. A mid-level Laravel developer can do this without vendor support.
• The package provides no server-side validation, geocoding, or normalization — we must add our own: lat ∈ [-90, 90], lng ∈ [-180, 180], both-or-neither pairing, and a decision on coordinate precision and storage type (DECIMAL(10,7) is the usual choice).
• Reverse geocoding (coordinates → human-readable address) is likely a separate call we own, either via the Maps Geocoding/Places API or a backend geocoder. Budget for it explicitly; do not assume the field does it.

Technical risk

• Adoption risk (primary): 15 stars and 0 dependents means effectively no community validation. Single-maintainer projects in the Filament ecosystem routinely stall when Filament ships a major version. Treat this as a "borrow the idea, own the code" dependency.
• Compatibility risk: Filament v3 → v4 and Livewire 2 → 3 changed asset registration and component lifecycle conventions. Verify the package's declared constraints before committing; a pinned, working install on our current Filament minor is acceptable, an unpinned one is not.
• Vendor/platform risk: Google Maps pricing, SKU tiers, and free-credit policy change on Google's schedule, not ours. Map loads are billed events; a heavily used admin panel with maps on every record view can generate real spend.
• Security exposure: the Maps JS key is public by definition. It must be HTTP-referrer restricted and scoped to Maps JS (and Places/Geocoding only if used), with a separate key per environment and a budget alert. An unrestricted key in a repo is a standard and expensive mistake.
• Client-side fragility: map initialization inside Livewire-morphed DOM, inside modals, and inside repeaters is a well-known failure class. CSP headers blocking maps.googleapis.com will silently break the widget.
• License hygiene: the package is MIT, but it wraps a third-party JS location-picker library. Confirm that library's license and that it is compatible with MIT redistribution/commercial use.

Key questions (to the maintainer, or to answer ourselves in the spike)

1. Which Filament and Livewire major versions are supported, and is there an active branch for Filament v4?
2. What exactly is the field's state shape — a JSON string, an array of {lat, lng}, or two bound scalar fields? This determines our persistence and validation design.
3. Does it support reverse geocoding, an address search box, or Places autocomplete out of the box, or is the map click the only input?
4. Does it render correctly inside modals, repeaters, and wizard steps (i.e., after Livewire DOM morphs)?
5. What is the failure behavior when the API key is missing, invalid, restricted, or over quota — console error, blank canvas, or a form-blocking state?
6. Is there CI, a test suite, and a documented breaking-change policy? Any response to issues in the last 6 months?
7. Which underlying JS library and version does it bundle, and under what license?

Integration Approach

Stack fit

• Appropriate only if the target admin is Filament v3 on Laravel 10/11 with PHP 8.1+. It is a poor fit for anything else, and unnecessary if location capture is a one-off — in that case a bespoke Alpine + Maps component (~1 day) avoids the dependency entirely.
• Confirm Google Maps is an acceptable vendor. If organizational policy forbids Google, substitute Leaflet/OpenStreetMap or Mapbox and the package is out.

Migration path

• Low-risk, incremental, and reversible if we follow one rule: the package must never own our data shape. Persist latitude, longitude, and optional formatted_address as plain columns on the domain model. The field is a widget that reads and writes those columns.
• Existing records with free-text addresses or null coordinates are unaffected; the field simply starts empty. No backfill is required to ship.
• Exit path is a single class swap: delete the third-party field from the form schema, drop in our own wrapper (see below), and no migration is needed.

Compatibility

• Pin the exact package version in composer.json; do not float. Record the Filament/Livewire versions it was validated against in the repo README or ADR.
• Gate the Maps key per environment (GOOGLE_MAPS_KEY in .env, never committed), with referrer restrictions and a spend cap in the Google Cloud console.
• Verify against our CSP: allow https://maps.googleapis.com and https://maps.gstatic.com in script-src, img-src, and connect-src, or the widget will fail invisibly.

Sequencing

1. Spike (0.5 day): install in a scratch branch, confirm Filament version compatibility, observe the state shape and failure modes, screenshot behavior in a modal.
2. Adapter (0.5–1 day): wrap it in our own App\Filament\Fields\LocationPicker class. Our forms reference our class, never the vendor namespace. This single decision converts an abandoned-package risk into a one-file fix.
3. Pilot (1 day): one resource, one form, full validation rules, key restrictions, and a documented fallback (manual lat/lng numeric inputs) for when JS fails.
4. Rollout: replicate across remaining resources only after the pilot survives a week of real use and the cost-per-map-load is understood.
5. Document: ADR covering why Google, the key-rotation procedure, the spend cap, and the swap-out instructions.

Operational Impact

Maintenance

• Assume we own it. With one maintainer and 15 stars, expect no timely Filament v4 support. Budget the adapter class as the insurance premium and plan for a fork or in-house rewrite at the next Filament major — roughly 1–2 developer days.
• Dependency surface is small (a Blade view, a JS asset, a field class), which keeps the ceiling on that maintenance low. This is the main argument in the package's favor.

Support

• No commercial support, no SLA, no security policy. Internal support model: our own adapter, our own docs, our own on-call. Escalation is "we fix it or we replace it," not "we open a ticket."
• Add it to the third-party dependency register with an owner and a review date, so it does not quietly rot.

Scaling

• Server-side cost is negligible: rendering is static, storage is two decimals, no queries added. It scales fine with admin concurrency.
• The scaling constraint is financial and external: Google Maps map loads are billed per SKU. Model the cost before wide rollout — maps on a list view with 50 rows is a very different bill from a map on a single edit form. Prefer showing the map only on the detail/edit view, with a static thumbnail or plain coordinates in tables.
• Watch the client-side bundle: an extra Maps JS payload on every admin page load is a UX cost on slow connections; load it lazily on the form that needs it.

Failure modes

Ramp-up

• A Laravel developer familiar with Filament needs about half a day to read the package, understand the state shape, and get a working field; a developer new to Filament and to the Google Cloud console needs 2–3 days including key setup, restrictions, and billing configuration.
• The non-obvious learning is not the PHP — it is the Google Cloud side: enabling the right APIs, restricting the key by referrer, setting budget alerts, and understanding which SKU each map view bills against. Assign that to whoever owns cloud billing, not to the intern.
• Produce a short internal runbook (key rotation, quota response, swap-out procedure) as part of the pilot; it is the artifact that makes this a low-risk dependency rather than an unowned one.