Filament Location Laravel Package

Getting Started

1. composer require theabhishekin/filament-location (confirm the exact vendor/package name and Filament version constraint from the README — the repo is TheAbhishekIN/filament-location, and v1.0.0 targets Laravel 11–12 / PHP 8.1–8.3).
2. Publish and configure the package (config + any assets) — you need a Google Maps API key configured before anything renders. Set it via .env so it stays out of version control.
3. Add the HasLocation trait to any model that stores coordinates, and make sure the underlying column exists (json column, or separate lat/lng columns — the package supports both).
4. First use case: drop LocationPicker into a resource form and LocationColumn into the matching table. A "pick a store/venue/address on a map" field is the fastest way to validate the whole stack (key, assets, storage format) end to end.

Where to look first: the package README for the exact LocationPicker / LocationColumn / trait method signatures, then the config file for map defaults (center, zoom, controls). Because this is a v1.0.0, treat the README as the source of truth rather than blog posts or older examples.

Implementation Patterns

Pick one storage strategy per model and stick to it. JSON keeps the form field trivial (one column, one component) but makes SQL sorting/filtering and index use awkward. Separate lat/lng columns cost you a bit of form wiring but play far better with ORDER BY, bounding-box filters, and DB spatial indexes. Use decimal(10,8) for latitude and decimal(11,8) for longitude if you go the column route.

Form usage is the standard Filament shape — a schema component inside your resource form, e.g. LocationPicker::make('location'). Configure map controls per-field rather than globally when different resources need different zoom/center behavior (e.g. a warehouse picker vs. a customer address picker).

Table usage is a column component, typically LocationColumn::make('location') with an icon type selected from the 8 built-ins. The click-to-open-Google-Maps-modal behavior is the main day-to-day win: reviewers see the pin and can inspect it without leaving the list page. If your model uses separate lat/lng columns, expect to need a getStateUsing() closure or an accessor that returns the pair consistently, since the column needs one value to work with.

Distance work belongs behind the trait, not in controllers. The HasLocation trait gives coordinate helpers and Haversine distance — good for "distance from this record to that point" on a detail page, sorting a small in-memory collection, or a "nearest depot" lookup among a handful of candidates. For anything table-sized, wrap the Haversine in a query scope but pre-filter with a bounding box on lat/lng first so the DB can use an index, then let Haversine refine.

Testing and CI. Fully covered per the release, and CI runs PHP 8.1–8.3 / Laravel 11–12 — mirror that matrix in your own app if you're touching the package. In your app tests, set a dummy maps key in phpunit.xml so component rendering doesn't blow up, and prefer asserting on the underlying state/coordinates over asserting on rendered map markup.

Multi-panel apps: register the package's assets/plugin in each panel provider that uses it, not just the default admin panel, otherwise the map silently fails to load in secondary panels.

Gotchas and Tips

• The Maps key is client-side. It ships to the browser, so lock it down by HTTP referrer restriction rather than pretending it's secret. Use a separate, server-restricted key if the package also calls Geocoding APIs.
• Billing and API enablement. A valid key with the wrong APIs enabled (Maps JavaScript vs. Geocoding vs. Places) produces a map that loads but doesn't geocode, or vice versa. Check the browser console and the Google Cloud API metrics before debugging your own code.
• Maps inside modals often render grey/blank. Map libraries measure container size on init; in a Filament modal the container is often still 0×0. If the column's map modal misbehaves, look for a resize/invalidate call in the package or dispatch one on modal open.
• JSON column ordering is database-dependent. Sorting or filtering on a JSON path behaves differently across MySQL, Postgres, and SQLite, and is usually non-indexed. If sorting/filtering on location matters, prefer dedicated columns — this is the single most likely source of "works locally, slow in prod."
• Guard against missing and degenerate coordinates. 0,0 is a real point in the Gulf of Guinea and a very common artifact of an empty form being cast to floats. Null-check before any distance calc, and decide explicitly what "no location set" renders as in the column.
• Trait name collisions. HasLocation is a popular name; if the model already has location-ish methods or accessors (getLatitudeAttribute, a location() relation), you'll get silent overrides. Dump class_uses() and check method conflicts before blaming the package.
• No breaking changes to plan for — v1.0.0 is the first tagged stable release, so there's no migration path from a prior version. Pin ^1.0 and review the changelog on minor bumps.
• Extension points: the column's icon set and the modal's map view are the natural places to customize; check whether views are publishable so you can override the modal without forking. Prefer config-driven customization over subclassing the components — subclassing Filament components across minor releases is where things break.