Filament Openstreetmap Laravel Package

Technical Evaluation

Architecture fit. The package is a thin, well-scoped addition to the Filament form layer rather than a platform: a single form component (MapInput), a value object (Point), an Eloquent cast (PointCast), and a PointFormat enum with 11 output formats. It owns no tables, no service provider logic beyond asset publishing, and no server-side rendering — the map is Leaflet + Alpine in a Blade partial with wire:ignore and $wire.entangle(). That means it slots into the existing Filament resource/forms architecture without touching our domain model or persistence conventions, and it is trivially removable. For a back-office "drop a pin" requirement (store/asset/site/venue coordinates), this is the correct shape of dependency: it replaces roughly the fiddly Leaflet-plus-Livewire-state plumbing we would otherwise build and maintain.

Integration feasibility. Low effort on the happy path: composer require, one vendor:publish --tag=filament-openstreetmap-assets step to place Leaflet under public/vendor/filament-openstreetmap/leaflet/, a nullable string or json column, a cast declaration, and a MapInput::make('point')->saveFormat(PointFormat::WKT) in the resource schema. No npm/Vite pipeline changes, no API key procurement, no per-request billing. The Point value object is independently usable (Point::fromValue() auto-detects formats, distanceTo() returns meters), so it can be reused for import/backfill scripts and non-Filament code paths even if we later swap the UI.

Technical risk. The risk is concentrated in maturity and correctness, not in architecture:

• Coordinate-order trap. Internally Point stores (lat, lng), but GeoJSON and WKT are (lng, lat). Combined with fromValue() auto-detecting format from string patterns, ambiguous inputs like "37.6173,55.7558" are a live data-integrity hazard. This must be covered by our own round-trip tests before any bulk import.
• Version volatility. A prior major (2.0.0) was explicitly "NOT COMPATIBLE WITH THE OLD VERSION," and 2.1.0 required re-publishing assets. Version pinning is mandatory, not advisory.
• No automated quality gate. There is no PHPUnit or PHPStan in the package root; testing is a manual laravel-test/ Laravel 12 + Filament 5 app. No documented CI. We inherit all verification responsibility.
• Framework coupling fragility. The Blade template depends on Livewire proxy internals ($wire.entangle() returning {initialValue, _x_interceptor} rather than a raw value). This is exactly the kind of implementation detail that breaks silently on Filament/Livewire upgrades.
• Third-party runtime dependencies. Tile serving relies on OpenStreetMap's public infrastructure (no SLA, attribution and usage-policy obligations). Geocoding (added in 2.2.0) uses the public Nominatim endpoint, which has a strict acceptable-use policy (~1 req/s, no bulk/automated use). Both are fine for internal, low-volume admin use and neither is fine for customer-facing or high-traffic use without a proxy or self-hosting.
• Ecosystem signal is nil. 28 stars, 0 dependents, single maintainer. There is no third-party bug surface, which is a compliment and a warning: nothing has been hardened by other people's production traffic.

Key questions to resolve before commitment:

1. What do the actual composer.json constraints pin — PHP upper bound, filament/filament (^3 only, or ^3|^4|^5), Livewire range? The README says ">=3" while the bundled test app is Filament 5; I want that verified against our installed version.
2. Does the maintainer have a release cadence, and is there any response commitment on issues? (Assume no.)
3. Is marker title escaped before being rendered in a Leaflet popup, or is it raw HTML? Marker titles sourced from user data would be an injection surface.
4. Does MapInput enforce requiredness and partial-coordinate validation (lat without lng), and what does it submit on a null/cleared value?
5. Is the translation layer (en, ru only) overridable via published lang files without forking?
6. Are there any tests at all for PointCast round-tripping across all 11 formats?

Integration Approach

Stack fit. This is a Filament-only play. If the admin surface is Filament v3+ on Laravel 10/11/12, PHP 8+, it fits cleanly. If any coordinate capture happens in a non-Filament surface (API ingestion, mobile app, console import), only the Point value object carries over — the MapInput does not. It is a single-point picker: no polygons, routes, geofences, or drawing tools, and no built-in address autocomplete beyond the Nominatim search bar. If the requirement is "customer-facing store locator with address search," scope that separately; this package supplies the back-office seed data for it, not the locator itself.

Migration path. Treat adoption as vendoring a component, not taking a dependency:

1. In the spike branch, add a nullable coordinate column (or two nullable numeric columns if we want to keep storage provider-neutral) — do not retrofit existing columns.
2. Decide the canonical persisted format once. WKT or the GeoJSON/array form preserves the option of moving to matanayadev/laravel-eloquent-spatial and PostGIS later; plain lat,lng string is the lowest-commitment choice. Document the coordinate order in the column comment and in the model.
3. Backfill legacy free-text coordinates through Point::fromValue() in a one-off artisan command with a dry-run mode and a rejected-rows report — never trust auto-detection blind.
4. Pin an exact version in composer.json, commit the published Leaflet assets (or publish deterministically in CI) so deploys are reproducible and don't depend on a writable-during-deploy public/ directory.

Compatibility. Validate against our exact Filament/Livewire/PHP matrix in a throwaway branch, not against the package's own test app. Check for collisions in public/vendor/ with other packages, and confirm the @assets block is compatible with our CSP if we enforce one (OSM tile domains and Nominatim must be allowlisted). If we run Filament 4/5, the entangle-based Blade code is the first thing to re-verify.

Sequencing.

1. Day 1–2: Timeboxed spike on one resource in a dev branch — install, publish, render, save, reload, read raw column value.
2. Day 2–3: Write our own tests: round-trip each of the 11 formats through cast → DB → cast; ambiguous-string parsing cases; null/partial coordinate handling; marker-title escaping.
3. Day 3: Go/no-go on fork vs. dependency. Given MIT licensing, 0 dependents, and single-maintainer risk, the default recommendation is to vendor the source into the repo (or a private fork) and own it.
4. Week 1: Data backfill (if any) behind a dry run; feature-flag the field on one low-traffic resource; document the manual-coordinate fallback for operators.
5. Week 2+: Expand to remaining resources; only then consider the geocoding search bar, and only if we've decided how we're proxying or rate-limiting Nominatim.

Operational Impact

Maintenance. This becomes our code the moment it ships. Budget a named owner and roughly 2–4 days per quarter in steady state: patching the vendored Leaflet copy (it is frozen at publish time and will not update itself), re-validating the Alpine/entangle template on every Filament or Livewire upgrade, and re-verifying the asset-publish step. Add PHPStan and PHPUnit coverage ourselves at adoption time — the upstream has neither, so our CI is the only gate. The upstream major-version history (a hard 2.0 break) means upgrades are deliberate, tested events, never a composer update side effect.

Support. There is no vendor, no SLA, and effectively no community — 28 stars and zero dependents means no Stack Overflow corpus and no one else's bug reports to learn from. Support is our on-call and our runbook. Document the two known gotchas prominently for the team: the (lat, lng) internal vs. (lng, lat) WKT/GeoJSON convention, and the Livewire Proxy unwrapping in the Blade template.

Scaling. Read/write load is negligible: one string or JSON column, one row per record, no server-side map rendering. The scaling ceiling is entirely external — OSM tile requests are client-side and governed by the tile usage policy (fine for tens of internal users, not for anonymous high traffic), and Nominatim is capped around one request per second with explicit prohibitions on bulk use. If geocoding becomes a real workflow rather than a convenience, either self-host Nominatim, put a caching proxy in front of it, or swap in a paid geocoder — and budget that decision separately. Spatial querying at scale (radius searches over large tables) requires the matanayadev/laravel-eloquent-spatial bridge plus a geometry column and spatial index; plan the column type with that in mind now, because migrating later is a data migration, not a config change.

Failure modes and mitigations.

• Missed asset publish → blank map, field unusable. Mitigate by publishing in CI and asserting the artifact exists in a deploy smoke test.
• Tile server throttling or blocking → map degrades to gray tiles. The display input below the map still accepts typed coordinates, so the field remains functional; document that fallback for operators and make it discoverable in the UI.
• Nominatim rate limit or block → search silently stops returning results. Detect and surface a message rather than failing quietly; cache results.
• Coordinate-order mix-up → pins placed thousands of kilometers away, discovered late. Mitigate with validation bounds, a round-trip test suite, and a sanity-check on the backfill output.
• Livewire/Filament upgrade breaks entangle → the field appears to save but writes stale or empty values. This is the most dangerous failure because it is silent; make "save, reload, verify raw column" a required step in every upgrade checklist.
• Ambiguous format auto-detection → wrong parse on import. Reject ambiguous strings in bulk ingestion rather than guessing.

Ramp-up. Developer onboarding is roughly half a day for the happy path given the README quality, plus the gotchas above. Ops requires exactly one new pipeline step (vendor:publish with that tag, or a committed-assets strategy) and confirmation that the web user can read the published directory. End users need no training beyond "click the map or type coordinates," but they do need to be told the map is a convenience and the coordinate value is the source of truth. Legal/licensing is a small but real gate: OSM data is ODbL and requires visible attribution, and the package is MIT — both are fine, both should be on the sign-off list rather than discovered post-launch.