Filament Maps Laravel Package

Technical Evaluation

Architecture fit

• Scope is narrow and specific: this is a Filament v3 admin-panel form field, not a general Laravel geospatial component. It fits only if our administrative surface is a Filament v3 panel. It does not serve storefronts, public APIs, PDF/report rendering, or non-Filament admin (Nova, plain Blade/Livewire, Inertia).
• Data contract is the useful part: the field writes a latitude/longitude scalar pair onto an Eloquent model. That means the data model stays ours even if the widget is later swapped — this package is the presentation layer only.
• It provides no geospatial query capability. Proximity search ("stores within 25 km"), bounding-box filters, and map clustering remain custom work against PostGIS/MySQL spatial indexes. Adoption does not reduce that scope; it reduces only the "let an admin drop a pin" scope.
• The stated use cases (addresses, store locators, delivery zones) are worth stress-testing: addresses imply geocoding, which this package does not do. A user can place a pin, but they cannot type an address and get a pin. That is a second, separate build-or-buy decision (a metered geocoding service), and it is likely larger than the map widget itself.

Integration feasibility

• Low mechanical cost: composer require, register the plugin on the panel, optionally publish config for default center/zoom, add the field to a form. A Laravel developer familiar with Filament should get a first map rendering in well under a day.
• The real cost is verification, not implementation: confirming which Filament major it targets, which tile/JS map library it pulls in client-side, and whether a third-party API key is required and where that key lives.

Technical risk

• Health signals are effectively absent. 0 stars and a 0.3 score mean no community adoption, no external bug surface, and no evidence anyone has run this in production. Treat it as unproven code, not as a mature dependency.
• Staleness against the platform. Last release 2024-09-02 pre-dates Filament v4. Filament form-field APIs are exactly what breaks at a major bump. Assume incompatibility with Filament v4 until engineering proves otherwise, and assume that if we adopt, we will personally own that upgrade.
• Correction to the assessment we were handed. The accompanying assessment-pm.md is generic boilerplate describing a different, mature package ("on its third major version", "background processing, authn/authz, media handling, payments"). Its central claims — v3.x stability, an upgrade-impact note for v3.0.0, a "support contract rather than a headcount" — do not transfer to this package. The "v3" in this package's description refers to Filament v3 compatibility, not the package's own semver. Engineering must not be sent to evaluate a v3.0.0 release that likely does not exist.
• Supply-chain risk sits in the browser, not the PHP. The PHP wrapper is thin; the actual dependency is an undisclosed JS map/tile provider. That provider's licensing, rate limits, and API-key model govern our risk far more than this package's MIT license does.
• Bus factor 1. Single-maintainer, MIT, no SLA. Fork cost is low precisely because the wrapper is small — that is the mitigation, and it should be documented, not assumed.

Key questions for engineering (blocking before commit)

1. What are the actual declared constraints — Filament version, PHP, Laravel — and what is the package's own version and changelog?
2. Which tile provider / JS map library does it load, does it require an API key, and is that key exposed in client-side config?
3. Does the field validate coordinate ranges, handle null/partial input, and degrade to a plain numeric lat/lng input if JS fails?
4. Are there tests and CI? Does the form field work in create and edit, and does it round-trip existing coordinates?
5. What column type does it expect (decimal(10,7) vs float), and does the docs' guidance lose precision?
6. Who maintains it, and is there any stated intent to support Filament v4?

Integration Approach

Stack fit

• Adopt only on the Filament v3 admin surface, on a pinned PHP/Laravel combination confirmed by engineering. If our admin is not Filament, this package is a non-starter regardless of quality — do not bend the platform around a 0-star widget.
• Keep the map field strictly on internal, admin-only screens. It is not appropriate for public, high-traffic pages.

Migration path

• The durable artifact is the schema, not the package: add latitude and longitude as decimal(10,7) nullable columns via a normal migration, with an index only if a bounding-box query is actually planned.
• Deliberately defer PostGIS / spatial types until a query requirement forces the decision. Storing plain decimals keeps the exit path open and avoids coupling our database to a UI choice.
• Wrap the field behind our own form-component or resource convention so a future swap is a component change, not a resource-by-resource rewrite. This is the concrete expression of the "exit path" principle.

Compatibility

• Pin an exact version in composer.json, commit the lockfile, and disable automated dependency bumps for this package.
• Add a cheap canary: a smoke test that renders the resource form and asserts the field mounts. That test is what will tell us when a Filament upgrade breaks it, rather than an admin discovering a blank map.
• Explicitly record the Filament v4 question as an open upgrade item with an owner, not as an unknown.

Sequencing

1. Spike (0.5–1 day): throwaway branch; install, render one form, confirm tile provider, key handling, and create/edit round-trip. Output: the written answers to the key questions above.
2. Pilot (lowest-risk surface): one internal admin-only resource — a store locator or branch list — where a degraded map is an annoyance, not an outage.
3. Decide the geocoding question separately. If the product requirement is "enter an address," the pilot will expose that the package delivers half the requirement; scope the geocoder as its own line item.
4. Standardize only after the pilot. One map-field pattern across panels, documented, pinned.
5. Public-facing: out of scope on the current evidence.

Operational Impact

Maintenance

• Functionally a vendored dependency. We own the upgrade path against future Filament majors, and we should budget for it rather than assume upstream will deliver.
• Mitigating factor: the wrapper is small, so the fork contingency is genuinely cheap. Write that contingency down — it is the difference between a calculated risk and an unmanaged one.
• Pin the version, freeze the lockfile, and review the package deliberately at each Filament bump rather than reactively after a broken admin screen.

Support

• MIT with no vendor, no SLA, and — at zero stars — no demonstrated responsiveness on issues. Plan for zero upstream support and budget internal ownership accordingly.
• Support cost is not headcount, but it is not zero either: it is one named engineer owning a small, unfamiliar code path.

Scaling

• Cost is almost entirely client-side: map JS and tiles load on every form render. Negligible at admin traffic volumes; unsuitable at public volume.
• The metered third-party dependency is the tile provider's quota and rate limits. An expired key or exhausted quota turns an admin-critical screen into a blank box. Key lifecycle needs an owner.
• Server-side cost is effectively nil, which is the honest argument in favor of adopting rather than building.

Failure modes

• Tile provider outage / expired key: map renders blank or grey, marker placement fails, and coordinates may save as null or stale. A user can believe they set a location when they did not.
• Silent null: no pin dropped on a required field. Mitigate with visible lat/lng readouts, required-field validation, and a plain numeric input fallback.
• Precision loss: wrong column type truncates coordinates, producing pins that are subtly wrong and very hard to debug later.
• Key exposure: provider key in client-visible config if not proxied or domain-restricted.
• Upgrade break: Filament bump silently breaks the field; the canary test is the control.

Ramp-up

• Low. A Filament-fluent developer learns the package in hours; the concept surface is a form field and two columns.
• The genuine ramp-up burden is organizational, not technical: absorbing ownership of an unproven dependency and answering the geocoding question the package leaves open. Those, not the install, are what a delivery plan needs to reflect.
• Recommendation: conditional proceed. Approve the spike and a single low-risk pilot; withhold standardization until the key questions are answered in writing and compatibility with our Filament version is demonstrated, not assumed.