Filament Leaflet Geosearch Laravel Package

Technical Evaluation

Architecture fit. heloufir/filament-leaflet-geosearch is a Filament form field that wraps Leaflet.js and the Leaflet GeoSearch plugin. It slots into the standard TALL-stack shape: a Laravel app using Filament panels, where an admin form needs a "pick a location" input that yields a lat/lng pair (and possibly a display label) persisted via Eloquent. The architectural surface is narrow and well-bounded — one custom field class, a Blade view, and a published JS/CSS asset bundle — so it does not impose a framework, service layer, or persistence convention on the host app. Fit is strongest in Filament v2-era applications (the release cadence, 2022-09-22 last release, and 22 stars all point to that generation). It is a poor fit for teams standardizing on Filament v3/v4, Vite-based asset pipelines, or Livewire 3, because the field's asset registration and lifecycle hooks were written against an older Filament contract.

Integration feasibility. Mechanically straightforward: Composer require, publish assets, register the field in a form schema, configure geocoding provider options, bind to model attributes. No queue workers, no migrations, no service providers beyond Filament's auto-discovery. Real feasibility hinges on three unknowns that must be verified in a spike, not assumed: (1) Filament version compatibility — the package likely declares filament/filament ^2.x and will not resolve against v3/v4 without a fork; (2) asset delivery — modern Filament expects Vite-built assets, whereas this package likely ships pre-built JS via Filament::registerScripts or an older Alpine/Livewire hook; (3) geocoder contract — Leaflet GeoSearch is provider-agnostic, so the package must expose configuration for Nominatim, Bing, Google, LocationIQ, etc., and it is unclear from the surface whether it does so cleanly or hard-codes a provider.

Technical risk. This is a high-risk dependency despite a small code footprint, and the scores reflect it (overall 1.09, opportunity 0.38). The dominant risk is abandonment: no release in roughly three years and 22 stars means effectively no upstream maintenance, no security patching, and no compatibility work as Filament, Livewire, and Leaflet evolve. Secondary risks are supply-chain and compliance: a client-side geocoder means end-user IPs and search strings leave your infrastructure to a third-party geocoding service, which carries GDPR/data-residency and provider-terms-of-service exposure (Nominatim's usage policy in particular forbids heavy or commercial use without self-hosting). Third is the API-key exposure surface — any provider key placed in the published JS is public. Fourth is correctness: client-side geocoding cannot be trusted for validation, so server-side re-validation of coordinates and bounds is mandatory regardless of what the field does. Fifth is asset/version drift — the moment the host app upgrades Filament, the field can silently break with no upstream fix path.

Key questions. Which Filament major version is the actual target, and does the package's composer.json constraint admit it? Which geocoding provider is configured by default, and can it be swapped or self-hosted? Does the field persist a structured value (lat/lng object, JSON, or two columns), and does it round-trip correctly on edit as well as create? Does it support reverse geocoding (map click → address) or only forward search? How are assets registered — legacy Filament asset API or Vite — and does that survive the host app's build pipeline? Is there any server-side validation hook, or is the coordinate the browser sends trusted verbatim? What is the license and provenance of the bundled Leaflet GeoSearch plugin and tile provider? And critically: is there a maintained fork or a credible alternative, or are we adopting this as a fork-and-own?

Integration Approach

Stack fit. Adopt only if the host application is a Laravel + Filament admin where the location picker is a convenience input, not a system of record. If the map is core product functionality (store locators, delivery zones, geo-fencing, routing), the thin feature surface here argues for building the field in-house on top of Leaflet or MapLibre directly, or adopting a more actively maintained map-picker package. Treat this as a UI component with a scoped blast radius, not a platform dependency.

Migration path. Because the package is effectively frozen, the realistic path is vendor-and-own rather than consume-and-track. Fork the repository, pin it as a VCS or path repository in composer.json, and plan to port the field class to the current Filament custom-field API if the host is on v3/v4. If the host is still on Filament v2 and staying there, direct adoption is viable with an explicit exit trigger (the next Filament major upgrade). In either case, wrap the field behind an internal abstraction — a single LocationPicker field class in the app's own namespace — so the third-party dependency is swapped by editing one file, not every form.

Compatibility. Verify against the actual matrix before committing: PHP version, Laravel version, Filament major, Livewire major, and Node/Vite if assets must be rebuilt. The absence of a recent release means the package is almost certainly untested against current Livewire 3 semantics (component hydration, wire:model behavior, deferred/lazy fields). Budget for a compatibility shim, not just an install. The geocoding provider is a second compatibility axis — confirm the chosen provider's JS SDK is still supported and its terms permit the intended traffic.

Sequencing. (1) Two-day spike: install in a throwaway Filament panel, confirm the field renders, searches, and round-trips a value on create and edit; capture exactly what breaks. (2) Decide adopt-vs-build based on that evidence, with a bias toward build if the spike shows any Livewire 3 friction. (3) If adopting, fork, pin, and wrap behind an internal field class. (4) Harden: server-side coordinate validation (numeric, within bounds, inside expected region), a documented reverse-geocode-on-save policy, and a rate-limit/fallback story for the geocoder. (5) Roll out to one low-traffic admin form before broad use. (6) Document the exit plan and set a calendar review at the next Filament upgrade.

Operational Impact

Maintenance. The effective maintenance burden is "we maintain it." With no upstream releases since September 2022 and a 22-star community, expect zero response to issues, no security advisories, and no compatibility PRs. Owning the fork means owning the Leaflet and Leaflet-GeoSearch version pins, the provider SDK integration, and the Filament field contract. This is manageable because the code surface is small, but it must be scheduled as recurring work, not assumed to be free.

Support. Internal support only. There is no vendor, no SLA, and a very thin community — Stack Overflow and GitHub search will yield little. Mitigate by documenting the field's behavior, the configured geocoding provider, the coordinate schema, and a known-issues list in the app's runbook, and by ensuring at least two engineers can read the field class and its Blade view. Do not let this become single-owner tribal knowledge.

Scaling. Three distinct scaling ceilings. First, geocoder throughput — free-tier providers such as Nominatim are rate-limited (roughly 1 request/second) and prohibit bulk or commercial use without self-hosting; a room full of admins searching simultaneously will hit limits and produce silent failures. Budget for a paid provider or a self-hosted geocoder if usage grows. Second, tile delivery — Leaflet tiles come from a third-party tile server whose availability and usage policy are outside your control. Third, and least risky, the client-side rendering cost is negligible at admin-panel concurrency levels. Note that all of this scales per-browser-session, not per-server-request, so capacity planning is about provider quota, not application servers.

Failure modes. Enumerate and instrument them: geocoder unreachable (search silently returns nothing — surface an explicit "search unavailable" state rather than an empty dropdown); provider API key expired or quota exhausted (401/429 — alert on these); tile server outage (map renders grey — cosmetic but alarming to users); Leaflet or Livewire JS version conflict after an unrelated frontend upgrade (field breaks inside otherwise healthy forms — the highest-likelihood failure); malformed or missing coordinates submitted (must be caught server-side, since the client is untrusted); and cross-origin or CSP violations if the host app tightens its Content Security Policy. Log geocoder errors with provider and status code, and add a health check or synthetic probe if the field is business-critical.

Ramp-up. Low for an engineer already fluent in Filament custom fields and Livewire — perhaps half a day to read the field class, Blade view, and asset registration. Moderate for anyone needing to debug the Leaflet/GeoSearch layer, because that requires familiarity with Leaflet's plugin model and the geocoding provider's JS API, neither of which the package abstracts away. The realistic ramp-up cost is not learning the package; it is learning enough of the surrounding ecosystem to own it after the upstream goes quiet — which, given the release history, is the state you are adopting into on day one.