Filament Map Picker Laravel Package

Technical Evaluation

Architecture fit

• This is a presentation-layer package, not infrastructure: a Filament v3 custom form field (Dotswan\MapPicker\Fields\Map) plus a matching infolist entry (MapEntry). Value is realized only if our admin surface runs Filament; for API-first products, headless storefronts, or non-Filament admin (Nova, Backpack, hand-rolled Livewire), it is out of scope.
• It is deliberately state-only: the field emits an array (lat, lng, optional geojson) and leaves persistence, validation, geocoding, and spatial querying to us. That is the right boundary — no hidden ORM assumptions, no opinionated migrations — but it means the picker is the cheap 20% of the work. The data model, coordinate validation, and backfill are ours.
• Rendering is client-side Leaflet over OpenStreetMap tiles with optional Leaflet-Geoman drawing tools. No server-side mapping, no geocoding, no reverse-lookup. Confirm this matches our mental model before scoping: this package answers "where on the map?" — not "what is at this address?"

Integration feasibility

• High. One composer require, field classes used exactly like native Filament fields, fluent configuration matching Filament conventions (->draggable(), ->zoom(), ->columnSpanFull()). A mid-level Filament developer can produce a working prototype in under a day.
• The README is unusually complete for a 136-star package: full option table, GeoMan reference, infolist usage, closure-based dynamic coordinates, and a documented refreshMap dispatch pattern for programmatic marker updates. That materially reduces discovery cost.
• Two integration patterns are blessed: (a) afterStateUpdated to fan the picker state into latitude/longitude/geojson columns; (b) afterStateHydrated to rehydrate from the record. Both are the correct Livewire idiom — but they are copy-paste snippets, not tested framework code. Treat them as recipes, not guarantees.

Technical risk

Key questions

1. Is Filament v4 supported, and on what timeline? Is there a published version compatibility matrix (Filament 3.x, Laravel 11/12, PHP 8.2–8.4)?
2. Is there a CI/test suite, and what does a breaking change look like — semver discipline or pragmatic?
3. Does the package support a configurable tile API key / provider abstraction, or only a raw tilesUrl string?
4. Is there an intended storage contract for geojson (JSON column vs. text), and is strip_tags actually necessary or a workaround?
5. What is the vendor's responsiveness on issues — and is there any commercial support relationship?
6. Does the field emit a single point only, or full geometry collections? This determines whether we need a spatial column (PostGIS/MySQL POINT) or just two decimals.
7. Accessibility: keyboard navigation and screen-reader behaviour for map interaction — is anything documented?

Integration Approach

Stack fit

• Fits a conventional Laravel + Filament v3 admin: Eloquent resources, Livewire forms, Blade/Livewire front-end asset pipeline. Nothing exotic required — no queue, no external service account, no SDK.
• Fits poorly if: the product needs public-facing (non-admin) map picking — the field is admin-panel-shaped and we would be adapting it; or if coordinates must be captured on a mobile native surface.
• Strongest use cases: geo-fenced membership/radius selection (rangeSelectField), delivery/service-area configuration, property or asset location capture, and admin-only GeoJSON authoring (zones, polygons) where Geoman's draw/edit/cut tools replace a separate GIS tool.

Migration path

• Schema first: add nullable latitude (decimal 10,7) and longitude (decimal 10,7), plus a geojson JSON column only if polygons/regions are genuinely in scope. Do not start with a spatial type unless query requirements justify it — the package emits plain numbers.
• Backfill existing address-only records through a geocoding pass (offline job, human spot-check) rather than asking operators to re-place markers manually.
• Ship the field behind a feature flag on a single resource; keep the old text inputs available for one release cycle so operators can fall back.

Compatibility

• Pin the version explicitly (^1.8) and commit the lockfile. Never float this dependency.
• Align the pin to the Filament minor we run in production; test the field on the exact same Laravel/PHP matrix in CI as the app, since field rendering failures show up as silent JS errors, not exceptions.
• Verify asset loading path (published vs. auto-registered) against our build pipeline — Filament custom fields are a frequent source of duplicated/missing Leaflet bundles when two packages each ship Leaflet.

Sequencing

1. Spike (1–2 days): install in a scratch Filament panel, wire one resource, exercise draggable/clickable/geoman/rangeSelectField, confirm tile loading in our CSP and network egress rules.
2. Data model & validation design: coordinate range validators, "not Null Island" rule, required-marker enforcement, GeoJSON size cap.
3. Pilot resource: one low-risk admin screen, feature-flagged, with a written rollback.
4. Tile provider decision: commercial key or self-hosted, attribution configured, egress allow-listed — before pilot traffic.
5. Rollout: template the field wrapper class, document the pattern, then extend to remaining resources.
6. Contingency: pre-scope a fork (it is MIT, ~one field class plus JS) and estimate the cost of owning it. Do this before the pilot, not after.

Operational Impact

Maintenance

• Low day-to-day cost: MIT license, small dependency surface, no server component, no background jobs, no external service credentials beyond tile hosting.
• Ongoing cost is concentrated in version-drift management: each Filament upgrade is a potential break, and the package's release history is the only signal. Budget a review at every Filament bump.
• Fork readiness is the real maintenance hedge. The wrapper class pattern (one internal LocationPicker field extending the vendor field) localizes any patch or fork swap to a single file.

Support

• Community-only support (GitHub issues). No SLA. Route questions through the vendor repo and keep an internal owner accountable for the dependency.
• Documentation quality is above average for the star count — the option table and infolist examples reduce internal support load. That said, options are numerous (40+ fluent methods), so publish an internal "approved subset" to keep field configuration consistent and reviewable.

Scaling

• Client-side rendering is essentially free per request; the operational scaling question is tile traffic, which is a function of admin sessions, not end users. Admin-scale usage fits comfortably on a commercial tile plan.
• Livewire state is the second scaling axis: GeoJSON polygons round-trip to the server on every state update. Large or numerous geometries will bloat request payloads and risk Livewire/proxy body-size limits. Cap geometry complexity; store as JSON, never as a serialized blob inside a text field.
• liveLocation(true, true, 5000) posts browser geolocation to the server on an interval. This is a real, sustained write path — restrict it to specific screens and never enable it on a resource the user leaves open in a tab all day.

Failure modes

• Tile provider outage or rate-limit (429): map renders blank or grey; the form still submits stale/zero coordinates. Mitigate with a non-blocking visual warning and server-side validation that rejects implausible coordinates.
• Null Island: default [lat: 0, lng: 0] silently persists as a valid-looking "off the coast of Africa" record. This is the highest-probability data-quality defect; block it in the validator, not the UI.
• Geolocation denial / non-HTTPS: showMyLocationButton and liveLocation fail on permission denial or insecure origin — degrades to manual placement. Acceptable, but should not be the only input path.
• CSP / egress changes: an internal security policy change blocking tile.openstreetmap.org or a CDN-hosted Leaflet bundle breaks the field silently in production with no server error. Add a smoke test that asserts the map container initializes.
• JS bundle collision: two Leaflet-shipping Filament plugins can conflict; symptom is a blank map or broken marker icons.
• boundaries() pan-back UX: the map snaps back when dragged outside the box, which reads as a bug to first-time users. Document it or constrain via minZoom deliberately.
• GeoJSON sanitization regressions: the strip_tags pattern means malformed or hostile geometry content can round-trip. Validate structure server-side (schema check, not tag stripping).

Ramp-up

• Developer: hours. The README's copy-paste examples are sufficient for a first pass; the fluent API mirrors Filament conventions closely enough that no new mental model is required.
• Operators: near-zero training. Map picking is a familiar interaction; the only behaviors needing explanation are click-to-place (non-default), the boundary snap-back, and the radius circle tied to rangeSelectField.
• Team-level onboarding: one internal doc covering the approved option subset, the storage contract, the validator rules, the tile provider config, and the fork contingency. That doc is the difference between a controlled dependency and a scattered one.

Bottom line: adopt with guardrails if we are committed to Filament v3 — pin the version, wrap the field, own the tile provider, and validate coordinates server-side. Defer if a Filament v4 migration is within two quarters, because that upgrade path is unproven and the package would become a schedule risk rather than a shortcut.