Filament Map Picker Laravel Package

Technical Evaluation

Architecture fit. filament-map-picker remains a Filament panel plugin that registers a custom form field. It slots into the existing form-schema layer (Filament\Forms\Components\Field), renders a Leaflet map in the browser, layers Geoman.io draw tools on top, and syncs geometry back into Livewire state via Alpine. That is still the correct extension point — additive, not invasive. Nothing in v1.6.5 changes this.

What it is not: a geo backend. No server-side geocoding, reverse geocoding, geometry validation, spatial indexing, or coordinate transformation. Any requirement beyond "let an admin drop a pin or draw a shape and persist it" is our build, not the package's. The release note does not add any of this.

Integration feasibility. Mechanically cheap and now marginally cheaper: one composer require, one ->plugin() registration in the panel provider, one MapPicker::make('location') in a resource schema. Realistic effort for a Filament-fluent developer is half a day including a smoke test. The non-trivial work is still the data contract — whether the field persists a single JSON blob, a GeoJSON string, or fans out to paired lat/lng columns — because that propagates into schema design, API serialization, and every downstream spatial query. The release note is silent on state shape; still verify from source before committing.

What changed in v1.6.5, and what it means.

• Laravel 12 support added (constraints now declared as 10/11/12). This widens stack fit and removes a near-term upgrade blocker on the Laravel side. It does not touch the Filament coupling risk, which is the one that actually bites.
• Tests and QA added. This directly retires part of the earlier "no evidenced test suite" finding. It is a genuine positive: a maintainer adding CI-adjacent test coverage is the single best early signal of stewardship. Treat it as evidence of intent, not evidence of coverage — confirm the tests exist in CI on PRs, and that they cover state hydration and asset registration rather than only happy-path mount.
• Active release cadence confirmed. The package is now at v1.6.5 with an incremental changelog, not a single Aug-2025 drop. Six-plus patch/minor releases with no breaking changes described is a healthy trajectory for a package this age.
• No breaking changes, no deprecations, no feature additions documented. This is a compatibility/QoL release. Our integration plan does not need to change.

Technical risk.

• Package identity (new, must resolve). The changelog URL points to vitormicillo/filament-map-picker, while our recorded package name is doode/filament-map-picker. Either we are tracking a fork, the vendor name differs from the GitHub org, or the original assessment captured the wrong identifier. Verify the exact Composer package name against Packagist before composer require — installing an unverified vendor string is a supply-chain hazard, not a typo.
• Vendor concentration (high, slightly improved). Still a single maintainer and no evidenced dependent cohort, but we now have a release cadence and a test addition. The "abandoned-on-arrival" scenario is less likely than it looked; the "we are the earliest serious adopter" scenario still holds. Adoption metrics were not re-supplied — re-pull stars/dependents rather than relying on the prior figures.
• Framework coupling (medium-high, unchanged). This is the open risk. The release note adds Laravel 12 but says nothing about Filament v4. Form-field internals — asset registration, state hydration, Alpine hooks — are exactly what churns between Filament majors, and a plugin that has not announced v4 support is unlikely to be ready on our timeline.
• Front-end asset provenance (medium, unchanged). No mention of bundling. Assume Leaflet and leaflet-geoman-free are still injected via CDN unless source proves otherwise. That is a hard external runtime dependency on every form render and a supply-chain surface we may not be permitted to accept.
• Tile provider terms (medium, unchanged). Default OSM tile usage is still not licensed for production traffic volumes. Policy/compliance risk that lands on us.
• Maturity signal. The prior composite score reflected low adoption, not low quality — that reading is now better supported. Low adoption remains, but it is no longer paired with "zero test evidence."
• AI-assisted QA (watch item, low). "Double-checking added using Claude AI" is a reasonable authoring aid, but it is not a substitute for deterministic CI assertions. Do not count it as coverage; count the committed tests.

Key questions to resolve before approval.

1. What is the canonical Composer package name — vitormicillo/… or doode/… — and which repo is authoritative? Resolve before install.
2. What Filament and Livewire version constraints does composer.json declare, and is v4 supported or planned? Still the top risk, still unanswered.
3. Do the new tests run in CI on PRs, and do they cover state hydration and asset registration, or mount-only?
4. What exactly is the persisted state shape — GeoJSON, raw coordinate array, or split fields — and is it configurable?
5. Are Leaflet/Geoman bundled and publishable, or CDN-only? Can assets be vendored for air-gapped or CSP-strict environments?
6. Does it support point-only, or arbitrary geometry (polyline/polygon/circle), configurable per field?
7. Does the maintainer document an upgrade or deprecation policy?
8. Does it emit server-side validation, or must we validate coordinates and geometry ourselves?
9. License hygiene: MIT for the package, but confirm the Geoman distribution and any pro-feature gating.

Integration Approach

Stack fit. Now targets Laravel 10/11/12 + Filament v3 panels with Livewire 3 and PHP 8.1+. If our panels are on Filament v3, fit is clean and Laravel 12 no longer forces a constraint pin. If we are mid-migration to Filament v4, this package remains a blocker on the migration path and should be deferred or forked — v1.6.5 does not change that.

Migration path. Most likely we already have latitude/longitude decimal columns. Two options:

• Adopt the package's native shape (a single JSON/geometry column) and add generated or virtual lat/lng accessors for existing read paths. Cleaner long-term, costs a backfill and a read-path audit.
• Keep split columns and bridge with ->afterStateUpdated() / ->dehydrateStateUsing() to decompose the map output. Lower migration cost, but we own the glue and inherit the package's state-shape change risk.

For any real querying (radius search, bounding box, "which zone contains this point"), plan on MySQL ST_* with a POINT/POLYGON column and an SPATIAL INDEX, or PostGIS if we are already there. Do not query against JSON.

Compatibility. Verify against our exact Filament minor and our exact Laravel minor — Laravel 12 support is declared, not proven against our dependency graph. Watch for Alpine/Livewire morph issues on repeaters and wizard steps where the map field re-initializes; the classic failure is a duplicated or orphaned Leaflet instance after a Livewire re-render. The new test suite, if it runs in CI, is a reasonable place to look for whether this class of bug is covered.

Sequencing.

1. Identity check (1 hour). Confirm the canonical Composer package name on Packagist and reconcile against vitormicillo vs doode. Do this first; everything else is wasted if we install the wrong artifact.
2. Spike (2–3 days). Install in a scratch panel, confirm state shape, asset loading, and behavior inside a repeater and a wizard. Read the source and the new tests, not the README.
3. Wrapper field. Build an internal GeoPointPicker component that extends or composes the package field. Still the single highest-leverage risk mitigation: one file to patch, one place to swap implementations, a clean seam if we fork or hand-roll a Leaflet field later.
4. Tile provider decision. Stand up a commercial or self-hosted tile source before any non-production demo, so the pilot reflects real terms of service.
5. Pilot in one internal admin resource, non-critical, behind a feature flag.
6. Data migration + rollout, with a validation rule requiring non-null coordinates on save so we never produce half-populated geometry.

Treat this as buy-and-insulate, not buy-and-depend. Budget the wrapper as part of the adoption cost. The v1.6.5 release modestly improves the odds the insulation is never needed; it does not remove the need.

Operational Impact

Maintenance. Assume we own this, but assume it slightly less grimly. Pin the version exactly, watch the repo for releases, and plan for a fork if the maintainer goes quiet or Filament ships a major. The demonstrated cadence (through v1.6.5) suggests a maintainer who is responsive today — that is a reason to relax the emergency-fork timeline, not to drop the wrapper. Ongoing cost is 1–2 engineer-days per year for version tracking plus a larger, unplanned hit whenever Filament majors land. Set a calendar reminder to reassess at each Filament major; the v1.6.5 note tracking Laravel 12 but not Filament v4 is precisely the pattern to watch.

Support. No commercial support, no SLA, no vendor to escalate to. The new tests do not change this — they reduce the frequency of surprises, not the cost of one. Internal runbook still required: how to re-vendor JS assets, how to disable the field if it breaks a panel, and the fallback (plain lat/lng numeric inputs). A single flag that swaps the map field for numeric inputs is cheap insurance and worth building.

Scaling. Unchanged. The map is client-side and per-form-instance, so server load is negligible — but every render is a burst of tile requests plus Leaflet/Geoman JS.

• Tile traffic is the scaling cost, and it is external. OSM's public tile servers will rate-limit or block us at meaningful admin concurrency. Budget for MapTiler/Stadia/self-hosted from day one; treat the default as development-only.
• Page weight. Leaflet + Geoman is meaningful JS on every form that uses the field. Load it only on resources that need it; avoid a map picker in a table with 50 rows of inline editing.

Failure modes to design for. All still live — none are addressed by a Laravel compatibility release:

• CDN blocked or CSP-strict environment → map silently renders blank, field still saves null. Add save-time validation that fails loudly.
• Tile provider 403/429 → gray canvas, no error surfaced to the user.
• Geoman init race after Livewire morph → duplicate layers, lost edits, or a marker that reappears after delete.
• Partial/legacy state (a lat without lng, or a GeoJSON string where an array is expected) → field throws on hydrate. Normalize on read.
• Large polygons inflate the Livewire payload and round-trip on every keystroke. Cap geometry complexity or make the field ->dehydrated()-only on save.
• Raw GeoJSON rendered into a template without escaping is an XSS vector if any non-admin can write geometry. Sanitize.

Ramp-up. Very low for a Filament-familiar engineer — under a day to productive use. The knowledge that matters is not the package; it is the spatial data model and tile infrastructure, and that is our intellectual property either way. Do not let the package's simplicity — or a reassuring patch release — disguise the fact that "geo" as a capability has a permanent operational footprint: tile budget, spatial index, and a geometry validation rule.