Filament Google Maps Laravel Package

Getting Started

The package ships three things you will use constantly: a Map form field (pick a point), a MapColumn table column (show a point), and map widgets (dashboard/summary views). Install it against the matching Filament major version — the package tracks Filament releases, so check the version constraint before composer require cheesegrits/filament-google-maps. Since v5.0.2 the package also supports Laravel 13 (the v4 line was merged forward), so check both axes — Filament major and Laravel major — against the constraints in the release you are pulling. A package that supports your Filament version may still not support your Laravel version, and vice versa.

1. Publish the config and set the key. Publish the package config, then put the key in .env:

GOOGLE_MAPS_API_KEY=AIza...

2. Enable the right APIs in Google Cloud. Maps JavaScript API (for the field/column/widget), Places API (for autocomplete), and Geocoding API (for server-side reverse geocoding). All are billed — attach a billing account before your first test or the map renders grey.
3. Add storage. The common pattern is a json column cast to an array holding lat/lng:

// migration
$table->json('location')->nullable();

// model
protected $casts = ['location' => 'array'];

4. Drop the field into a resource form.

use Cheesegrits\FilamentGoogleMaps\Fields\Map;

Map::make('location')
    ->defaultLocation([51.5074, -0.1278])
    ->zoom(14)
    ->draggable()
    ->clickable();

First use case to prove the integration works: open the edit form, click the map to move the marker, save, then confirm the JSON in the DB changed. If the map is grey or throws a console error, it is almost always an API/key problem, not a Filament problem.

Implementation Patterns

Map field as the system of record. Store lat/lng and let the field own the picking UX. Reverse geocoding is the killer feature — drag the pin, get structured address components written back to your model:

Map::make('location')
    ->draggable()
    ->clickable()
    ->autocomplete('address')          // search box bound to your address field
    ->reverseGeocode([
        'street' => '%S %n',
        'city'   => '%L',
        'zip'    => '%z',
        'state'  => '%A',
        'country'=> '%c',
    ]);

This is the pattern for "store coordinates, display a human address." Format specifiers (%S, %n, %L, %z, %A, %c) map to Google address components — don't expect free-form strings.

Geocomplete when the address is the system of record. If your users think in addresses and the coordinates are derived, lead with Geocomplete and fan the result out to other fields:

Geocomplete::make('address')
    ->isLocation()
    ->updateLatLng('latitude', 'longitude')
    ->updateMap('location')
    ->placeId('google_place_id')
    ->countries(['gb'])
    ->types(['address']);

This avoids asking users to drag a pin, and gives you a place_id for cheap re-lookups later.

Table column for triage views. MapColumn is for scanning, not editing — a small inline map or pin that lets an operator confirm a record is geo-coded without opening it. Use it in list views where "is this address right?" is the daily question. Keep height() small and don't enable interactive maps on 50-row tables; the map loads are billed and the page gets heavy.

Widgets for coverage/ops dashboards. Widgets take markers from your own query, so the pattern is: build a query, map rows to marker arrays, hand them to the widget. This is where the package earns its keep for field-service, delivery, or store-locator style apps — one panel page showing every record missing coordinates is a genuinely useful internal tool.

Validation. Treat location as required-but-shaped: ->required() plus a rule that both lat and lng are present and numeric. A half-filled array is the most common data corruption this package produces.

Gotchas and Tips

• Key restrictions break server-side calls. A JavaScript key restricted by HTTP referrer is correct for the browser and will fail for Geocoding/Places calls made from PHP. Use two keys: a referrer-restricted browser key and an IP-restricted server key, and keep them in separate config entries. "The map works but reverse geocoding silently writes nothing" is nearly always this.
• Reverse geocoding is a per-drag API call. Dragging a marker generates a request each time it settles; on a form users fiddle with, that is real money and real latency. Debounce expectations, and consider geocoding on save in an observer instead of on drag if your volume is high.
• Cached config hides key changes. After editing .env, run php artisan config:clear. A stale cached config is the second most common "why is the map grey" cause.
• Assets. After install/upgrade run php artisan filament:assets and clear views. If the map renders once and then disappears after Livewire navigation, it's an asset/Alpine re-init issue — wire:ignore around the field and stable element IDs help.
• Nested fields need unique IDs. Map inside a Repeater or Builder will collide unless you give each instance a distinct ->id() derived from the item key. Two maps fighting over one DOM node is a confusing bug to chase.
• Column vs form field are different classes. Don't try to reuse Map in a table; MapColumn has its own, smaller option set (showMap(), zoom(), height()). Reading the wrong class's docs wastes an afternoon.
• Storing separately. If your schema already has latitude/longitude columns, point the field at those rather than migrating to JSON — the field supports binding to discrete attributes, which keeps existing reporting queries intact.
• Version skates on two axes. v5.0.2 is essentially the v4 line merged forward with Laravel 13 support. Because the branch history has been merged rather than published as a major, pin the exact version in composer.json ("cheesegrits/filament-google-maps": "^5.0.2") and re-read the config/asset publishing step after any Laravel or Filament upgrade — a Laravel bump on a stale package constraint is the classic "works locally, fatal in CI" trap.
• Testing. Never hit Google in CI. Fake the geocoding HTTP calls, or gate the geocode-on-save path behind a config flag so feature tests can disable it. A test suite that depends on a live API key will be flaky and expensive.
• Extension points worth knowing. Publish the package views to restyle markers and info windows; extend the field class if you need custom Alpine behaviour; supply markers to widgets from any query, which makes widgets the easiest place to add bespoke map views without touching the core field.
• Cost model. Map loads and Places/Geocoding calls are separate SKUs with separate free tiers. A dashboard with several map widgets on one page multiplies loads. Audit the panel's map surface area before you assume it's free.