Filament Leaflet Laravel Package

Technical Evaluation

Assessment basis: Initial evaluation, pinned to eduardoribeirodev/filament-leaflet v5.2.2. No prior assessment exists, so this establishes the baseline. v5.2.2 is a patch release: no breaking changes, no deprecations, no new configuration surface — one notable defect fix plus resilience improvements.

Architecture fit

• The package is a Filament form-field plugin that wraps Leaflet map rendering and a geocoding search input into a Livewire-backed field. This is the correct architectural seam for our admin panels: it stays inside Filament's form schema and state lifecycle rather than introducing a parallel front-end stack.
• Coordinate handling is exposed as a model cast, with configurable cast columns and a coordinateLabelUsing() callback. That is a clean separation of concerns — the package owns map interaction and persistence shape; the host application owns reverse-geocoding, address formatting, and any domain-specific labelling. We are not forced into a vendor's geocoder.
• Geocoding appears to resolve through a provider abstraction invoked from the field. This means an external dependency sits inside our authoring flow, which is an architectural coupling we must accept deliberately rather than by accident.

Integration feasibility

• Integration is a standard Composer install plus Filament asset/config publishing. Low mechanical effort.
• The real effort is schema and data ownership: we must decide whether coordinate data lives in a single cast-managed column or in existing separate latitude/longitude columns, and confirm the cast supports our naming via the custom-column support added in this release.
• Front-end integration is constrained to our existing Filament panel build; no design-system work is implied.

Technical risk

• Data-integrity risk (materially reduced by 5.2.2): prior to this release, GeoSearchInput selected the last search result regardless of which option the user clicked. That class of silent wrong-coordinate write is the most expensive failure mode for a location field, because it looks like a successful save. We should treat 5.2.2 as the minimum acceptable version and reject any pin at or below 5.2.1.
• Coverage-maturity signal: the defect survived to a patch release and was caught via a model-cast round-trip regression check, not an end-to-end UI test. This suggests the plugin's test suite is lighter on interactive behaviour than we would want. Our own acceptance testing must cover the click-select path, not just persistence.
• Third-party geocoder dependency: availability, rate limits, terms of service, and credential handling for the search provider are now in our critical path. This is unmanaged risk until we choose and configure a provider.
• Asset pipeline coupling: the release includes a refreshed distributed CSS build and Leaflet pane/tooltip stacking corrections. Any upgrade requires re-publishing assets; a deploy that ships new PHP without new CSS will produce subtly broken map chrome.
• Maintainer concentration: single-maintainer open-source package, fast minor cadence (5.2.x), no commercial SLA.

Key questions

1. Which Filament major versions and PHP/Laravel floors does v5.2.2 support, and which of our panels are on that matrix today?
2. Which geocoding provider(s) does the search input call, is the call server-side or browser-side, and what are the rate limits, ToS, and data-residency implications?
3. Is there a manual lat/lng entry fallback if the geocoder is unreachable, or does the field hard-block form submission?
4. Does the Coordinate cast write to a single column or to caller-supplied columns, and can it coexist with our existing latitude/longitude schema without a data migration?
5. What is the keyboard/screen-reader path for the map input, and does textMode(true) cover our accessibility baseline?
6. Licensing (permissive vs. copyleft) and whether asset publishing is required on every upgrade.

Integration Approach

Stack fit

• Fits naturally into Laravel + Filament + Livewire panels. No additional JS framework, no separate API service, no state duplication outside Filament's form state.
• The coordinateLabelUsing() callback is the correct extension point for our own reverse-lookup or stored-address display; we should implement labelling in application code and keep the package unaware of our address model.

Migration path

• Phase 0 — spike branch: install 5.2.2, publish config and assets, wire one throwaway resource, verify the search-select round trip against the Coordinate cast.
• Phase 1 — schema decision: confirm whether the cast maps to new columns or our existing ones. If new, prepare a backfill; if existing, verify custom cast column support against a staging copy of production data, including null and malformed coordinate rows (the release explicitly hardens invalid-stored-data handling, so this is now testable).
• Phase 2 — provider selection: choose the geocoder, provision credentials via environment/secret storage, and implement caching so repeated lookups do not burn quota.
• Phase 3 — pilot: one internal, low-traffic admin resource; instrument geocoder latency and failure rate.
• Phase 4 — rollout: remaining resources in cohorts; publish a runbook entry covering asset re-publication on upgrade.

Compatibility

• Pin explicitly to ^5.2.2 (never *), and record the tested Filament/PHP/Laravel tuple in our dependency notes.
• Add asset re-publication to the standard deploy checklist before this package ships to production.
• Confirm that any panel-level CSS customisations still win after the distributed CSS refresh.

Sequencing

1. Confirm version matrix and licence.
2. Spike + acceptance test on the click-select path (regression from #33).
3. Schema/cast decision and backfill plan.
4. Geocoder procurement, credentials, caching.
5. Pilot resource.
6. Cohort rollout + runbook + upgrade cadence policy.

Operational Impact

Maintenance

• Low code footprint but non-zero upgrade tax: patch releases are frequent and each may include a rebuilt CSS asset, so upgrades are "install, publish, re-verify map chrome" rather than pure Composer bumps.
• Budget roughly one maintenance window per quarter to review the changelog and re-run the map acceptance checks. Pin and upgrade deliberately; do not float.

Support

• Community/GitHub-issue support only, no vendor SLA. Internal ownership must be assigned to a named engineer.
• Because the package is small, our mitigation is containment: keep map interaction isolated to Filament resources so a package-level regression blocks authoring, not the whole admin panel.

Scaling

• The scaling limit is the geocoder, not Laravel: lookups scale with editor keystrokes and saved-record counts. Mitigate with debounce, server-side caching of resolved coordinates, and a quota alert.
• Map tile requests scale with concurrent editor sessions against the tile provider; confirm the provider's usage policy tolerates our peak admin concurrency.
• No database-level scaling concerns beyond indexing whatever columns back the cast.

Failure modes

• Geocoder outage or timeout → search unusable; without a manual-entry fallback, editors cannot save locations. Treat manual coordinate entry as a required safety valve.
• Wrong-result selection (the #33 class) → silently incorrect coordinates. Mitigated at 5.2.2, but must remain in our regression suite permanently.
• Missing asset publication after upgrade → broken panes, tooltips, or unstyled controls. Caught only by visual QA.
• Invalid/legacy stored coordinates → release improves handling, but we should still surface a validation warning rather than silently rendering a default map centre.
• Provider ToS or quota breach → sudden hard failure across all location forms; alert on error rate and quota consumption.

Ramp-up

• Developer ramp-up: approximately half a day for an engineer already fluent in Filament form schemas; the API surface (field, cast, label callback) is small.
• Editor ramp-up: short but necessary — guidance on search-vs-manual entry and on verifying the selected pin matches the intended address.
• QA ramp-up: define a small acceptance script covering search-select correctness, saved-record label rendering, text mode, and map rendering after an asset publish. Reuse it on every upgrade.