Filament Leaflet Map Picker Laravel Package

Technical Evaluation

What it actually is: a single-purpose Filament Forms field that embeds a Leaflet.js map to let an operator pick or adjust a latitude/longitude pair, and writes those values into form state. It is a UI convenience component, not a geo platform: no geocoding, no reverse-geocoding, no address search, no routing, no spatial querying, no server-side geo logic.

Architecture fit

• Only a fit if the target application is Laravel + Filament (v3 or v4 — must be confirmed). In a non-Filament admin (Nova, Backpack, custom Blade/Livewire, Inertia/Vue), the package is unusable and the code inside is a thin Leaflet wrapper you would reimplement in under a day.
• Value is confined to back-office data entry. It does nothing for public-facing maps, storefront locators, or API consumers; those need a separate rendering path regardless.
• Clean architectural boundary: it owns presentation and coordinate state only. Persistence, validation semantics, and column design remain ours, which is the right split.

Integration feasibility

• Low effort. Composer install, auto-discovered service provider, add the field to a form schema, add two nullable decimal columns. No queue workers, no migrations shipped by the package, no external service account.
• Main friction points are asset delivery (Leaflet JS/CSS via CDN vs published assets), Content-Security-Policy, and air-gapped/on-prem deployments where a public tile server is unreachable.

Technical risk (ranked)

1. Filament major-version coupling. Filament ships breaking changes between majors; a 40-star package with one maintainer is unlikely to track releases quickly. This is the dominant risk and it is a deadline risk, not a runtime risk — it surfaces the day you upgrade Filament.
2. Bus factor / longevity. Single maintainer, minimal adoption, no visible support policy or SLA. Assume you may own the code.
3. Asset and CSP behavior in production builds (Vite pipeline, Livewire re-renders, strict CSP policies).
4. Tile provider terms. OpenStreetMap's tile usage policy prohibits heavy/commercial use of the default tile endpoint; tile sourcing is our decision and our liability, not the package's.
5. Test coverage unknown. Geographic input is easy to get subtly wrong (sign conventions, precision loss, hemisphere, state shape after Livewire round-trips).

Key questions to answer before committing

• Which Filament major versions are supported, and what is the stated PHP/Laravel matrix? Is there a CI matrix?
• What is the exact form-state contract — two separate fields, a nested array, or a single delimited string? Does it degrade to manual numeric entry if JS fails?
• Are Leaflet assets bundled/published or CDN-loaded? Is the tile URL configurable, and can it point at a self-hosted or commercial provider?
• Does it validate coordinate ranges, or is that entirely on us?
• Is there a fallback plain-text input for accessibility, keyboard-only use, and no-JS scenarios?
• What is the upgrade history across Filament majors — did it ship a v4-compatible release, and how long did it lag?

Integration Approach

Stack fit gate (all must be true)

• Laravel + Filament panel is the actual admin surface.
• Coordinates are captured/edited by humans, not ingested from devices or third-party feeds (those should not route through a map widget).
• The team accepts owning a fork if the maintainer goes quiet.

Migration path

• Add nullable decimal(10,7) latitude and decimal(11,8) longitude columns (or a single JSON column if the app already favors that; a POINT/PostGIS column only if spatial queries are genuinely on the roadmap — do not add PostGIS for a form widget).
• Backfill from any existing free-text address/lat-lng fields, with a reconciliation report of rows that fail range validation.
• Keep the old input available read-only for one release cycle so operators can spot bad backfills.
• If replacing a map in a public-facing view, do not reuse this component — it is admin-only and will not carry the styling, SEO, or performance requirements.

Compatibility

• Pin the Filament major in composer.json and verify the package's constraint resolves cleanly; do not let a Filament upgrade float this dependency implicitly.
• Validate in a production-like build (not php artisan serve): confirm assets survive the Vite/publish step and render inside a Livewire modal, where Leaflet sizing bugs most often appear.
• Check CSP headers early — a blocked tile or script origin is a two-minute fix if caught in the spike and a launch blocker if caught in UAT.

Sequencing

1. Spike (0.5–1 day): install in a branch, wire to one throwaway form, verify map renders in a modal, state round-trips through Livewire, and validation rejects out-of-range values. Exit criteria: renders under production CSP and asset build.
2. Pilot (1 form): ship behind a feature flag to internal operators only. Instrument for JS errors and empty-tile failures.
3. Harden: add server-side range validation, a manual numeric fallback input, and a helper text convention for coordinate order (lat/lng vs lng/lat is a recurring operator error).
4. Roll out to remaining forms; document the tile provider choice and its usage limits.
5. Contingency: budget ~1–2 developer days to vendor or reimplement the field. Given the small surface area, this is a cheap insurance policy and should be the default assumption rather than a surprise.

Operational Impact

Maintenance

• Steady-state cost is near zero; the real cost is a recurring one-to-two-day task each time Filament ships a major, plus occasional Leaflet security updates.
• Recommend vendoring/forking at adoption time rather than after abandonment — forking later means re-discovering undocumented behavior under time pressure.
• Track the package's release cadence as a leading indicator. A release date far in the past relative to Filament's latest major is the signal to fork proactively.

Support

• Community-only support: GitHub issues, no SLA, no vendor escalation path. Internalize that the escalation path is "a developer reads the source," which is feasible here because the source is small.
• Document the fork point and the local patches in the repo README so a future maintainer knows what diverged.

Scaling

• Server-side impact is effectively nil: tiles are fetched by the browser, not proxied through the app. No added load on the PHP workers, queue, or database beyond two numeric columns.
• What scales badly is the tile provider relationship, not the app. Default public tile endpoints will throttle or block you as internal usage grows; plan for a commercial or self-hosted tile source before rollout broadens.
• Client-side cost: Leaflet plus tiles per form render. Negligible per operator, but if the map appears on high-traffic public pages (it shouldn't), treat it as a real bandwidth line item.

Failure modes to design for

• Tile server unreachable / CDN blocked: map renders grey. The form must still accept manually typed coordinates; otherwise a third-party outage blocks data entry entirely.
• JS exception inside the Livewire component: can break the surrounding form render, not just the map. This is the highest-severity failure and argues for wrapping the field so a failure degrades to a text input.
• CSP / asset pipeline regression after an unrelated frontend change — silent until someone opens the form.
• Bad state shape: coordinate order confusion or precision truncation writing silently wrong points. Mitigate with server-side validation and a "show on map" confirmation in review screens.
• Provider policy violation (bulk use of public tiles) resulting in blocked requests and, in the worst case, an account-level problem.
• Abandonment upstream — manifests as an inability to upgrade Filament, which becomes a security-patch bottleneck for the whole admin panel.

Ramp-up

• Roughly half a day for a developer already fluent in Filament forms; closer to a day for someone new to Livewire component state, mostly spent on asset/CSP troubleshooting.
• Add internal documentation covering: coordinate storage format and column precision, tile provider and its terms, the manual-entry fallback path, and the fork/upgrade procedure. That documentation is the actual durability investment — the package itself is the cheap part.