Filament Openstreetmap Laravel Package

Product Decisions This Supports

• Build vs. buy for "drop a pin" input. Any Filament admin panel needing coordinates for stores, assets, job sites, venues, or leads faces the same call. Building it means Leaflet plus Alpine plus Livewire state entanglement — fiddly, easy to underestimate. This package is the buy option: one form component (MapInput), one Eloquent cast (PointCast), one publishable asset bundle.
• Map vendor and cost decision (commercial, not just technical). OpenStreetMap tiles with a vendored Leaflet copy means no API key, no per-request billing, no Google Maps ToS/attribution overhead. That removes map cost from the per-seat/per-load budget conversation and unblocks internal tools where a billed Maps key would stall procurement.
• Geocoding scope decision. v2.2.0 adds an address search bar backed by Nominatim (free, no key). That changes the estimate for "operators shouldn't have to know lat/lng" from separate project to config toggle — but it also introduces a third-party usage-policy and rate-limit dependency worth a deliberate yes/no.
• Storage-format and lock-in decision. The bundled Point value object plus PointFormat enum (11 formats: lat/lng, lat-lng, WKT, GeoJSON, DMS, Google/OSM/Yandex URLs, {latitude,longitude}, [lng,lat]) and an optional matanayadev/laravel-eloquent-spatial bridge mean choosing a simple string column today does not block PostGIS or spatial queries later. You can migrate at the input layer without re-architecting.
• Curated-selection vs. free-form positioning. markersOnly() (map clicks disabled, search filters a marker list) is a genuinely different product behaviour: "pick one of our branches" rather than "place an arbitrary point." That is a UX and data-quality decision, not a code detail — it is the difference between clean normalized data and operators dropping pins 400m off.
• Roadmap scoping for geo-adjacent features. Store locators, service-area pinning, field-service job sites, marketplace listings, facility registries, "nearest branch" seed data — all of these need point capture in the back office before any customer-facing map exists. This unblocks the data-capture prerequisite cheaply.
• Localization scope as an estimate input. Ships en and ru only. If the launch market is neither, translation work belongs in the ticket, not in a surprise.

When to Consider This Package

Consider it when all of these hold:

• The admin surface is Filament v3+ on PHP 8+. Non-Filament stacks get nothing from it.
• The need is single-point capture by a human in a form — not polygons, routes, geofences, or drawing tools.
• The feature is internal/back-office, where a degraded map is an inconvenience rather than a customer-visible outage.
• You are prepared to own the code: 28 stars, zero dependents, single maintainer, and a v2.0.0 that was explicitly not backward compatible. Treat adoption as a fork, not a dependency.
• You accept an engineering review as a precondition. There is no PHPUnit or PHPStan in the package root; testing is a manual laravel-test/ Laravel 12 + Filament 5 app. Plan to add your own tests around whatever you adopt.
• You have a coordinate-order guard in mind. Internally Point stores (lat, lng), but GeoJSON and WKT are (lng, lat), and fromValue() auto-detects format from string patterns. That is a live data-integrity trap — validate on write, assert in tests.

Look elsewhere (or build) when:

• You need multi-geometry editing (polygons, service boundaries, delivery zones, routes). Wrong abstraction; go to a dedicated geometry library or a paid drawing SDK.
• It is customer-facing UI with uptime and accessibility expectations. You want a maintained vendor or full in-house ownership.
• Your team requires SLA, security review, or dependency-policy sign-off that a 28-star single-maintainer package will not clear.
• You need bulk geocoding or reverse-geocoding at volume — Nominatim search is a form-field convenience, not a batch geocoding service.
• Your spatial requirements are already satisfied by existing PostGIS tooling; adding a second coordinate path creates ambiguity.

Recommendation: timeboxed 1–2 day spike inside the real admin panel, exercised against real data and the two or three formats you intend to store. If it clears, vendor the source into the repo or a private fork so asset publishing, Leaflet upgrades, and the Nominatim dependency stay under your control.

How to Pitch It (Stakeholders)

To executives: There is a small, focused open-source component that lets our operators set map coordinates directly inside the admin panel, using OpenStreetMap. The business case is cost and friction: no map API key, no per-load billing, no vendor contract. We avoid a build project and an ongoing Maps bill at the same time, and it closes a prerequisite that blocks several geo features already on the roadmap. The trade-off is maturity — young package, one maintainer, no downstream users — so the ask is a short evaluation, then a decision to own a copy internally. Risk is contained: it is back-office tooling, not customer-facing, and the coordinate data it writes is portable to any future mapping system.

To engineering: It is a Filament form field (MapInput) plus an Eloquent cast (PointCast) and a Point value object with an 11-format enum. Leaflet is vendored and published via vendor:publish --tag=filament-openstreetmap-assets. The Blade component uses wire:ignore with Alpine x-data and $wire.entangle(); note the known Livewire proxy gotcha where entangle() returns a proxy object, not a raw value — the package already unwraps initialValue, so don't "simplify" that code. Watch the coordinate order: internal storage is (lat, lng), GeoJSON/WKT are (lng, lat), and parsing is pattern-based auto-detection — add explicit validation and unit tests around our chosen format. No PHPUnit or static analysis ships in the package; assume we add both. Our plan is a two-day spike, then vendor the source so Leaflet and Nominatim usage stay under our control.