Filament Google Maps Laravel Package

Technical Evaluation

Architecture fit. cheesegrits/filament-google-maps is a pure Filament plugin — a service provider with auto-discovery, a set of Livewire/Alpine-backed form fields, a table column, and a dashboard widget. It introduces no backend service, no queue workers, and no persistent daemon; it is a thin client-side wrapper around the Google Maps JavaScript API plus server-side geocoding calls. For any application already running Filament panels, this is a native-fit component rather than an integration: it slots into the existing Resource form()/table() schemas and the Panel::widgets() registry, and persists coordinates into columns you already control. There is no new bounded context, no data store, and no cross-service contract to govern — which is the main reason the architectural risk is low even though the vendor risk is not. v5.0.2 does not change this picture; it is a compatibility release, not an architectural one.

Integration feasibility. Composer install, config/asset publish, an API key in .env, a model trait/interface, and a schema entry. Realistically a half-day spike and one to two days to productionise (key restrictions, billing controls, schema decisions). The two genuine design decisions are unchanged: (a) storage shape — discrete lat/lng columns versus a single JSON/GeoJSON column, which affects queryability and later spatial indexing — and (b) whether the map is interactive everywhere or only on edit forms, which drives API cost.

The release note for v5.0.2 — "Merge v4, package should now work with Laravel 13" — is the only substantive signal in this release, and it is a weak one. It tells us the maintainer has brought forward a v4 branch and added Laravel 13 support. It does not state which Filament major the release targets, whether Laravel 12 and Filament v3 are still supported, whether the merge introduces breaking changes (a branch merge of that shape frequently does), or what the actual minimum PHP version now is. Treat the note as evidence of maintenance activity, not as a verified compatibility matrix. The one-line note is itself a governance signal: this package does not publish disciplined changelogs, so our upgrade verification has to be empirical.

Technical risk. Ranked:

Key questions (revised for this release). Does v5.0.2 support Filament v3, v4, and the Filament major paired with Laravel 13 — or has it dropped v3? What is the new minimum PHP version, and does our fleet meet it across every panel? What actually changed in the v4 merge, and is there a changelog beyond the merge line? Does the release carry a migration guide or require republishing assets? Do we run Laravel 13 anywhere yet, or is this release ahead of our own upgrade cycle — in which case we stay pinned and re-evaluate on our next Laravel bump? Carried forward: is Google Maps contractually acceptable versus Mapbox/Leaflet+OSM? Who owns the Google Cloud billing account and key rotation? Do we need geometry persistence or just a point picker? Is the dashboard widget worth its billable loads? What is our fork/vendor fallback if the package is abandoned?

Integration Approach

Stack fit. Assumes Laravel 10+/PHP 8.1+, Filament v3 or v4, Livewire 3, and Tailwind-based panel theming. v5.0.2 extends the upper bound to Laravel 13 but does not raise the floor or clarify the Filament pairing — confirm the actual constraint set from composer.json rather than from the release note. It remains a natural fit for an admin/back-office panel doing store locators, delivery zones, asset geotagging, or property/site records, and remains not a fit for customer-facing public maps — the admin-panel UI conventions, Filament asset pipeline, and authenticated routing make it the wrong tool there; use the Google Maps SDK directly for the front end.

Migration path.

1. Sandbox panel spike: install, publish config and any bundled migrations, add the trait/interface to one throwaway model, render a field and a column.
2. Read composer.json on v5.0.2 directly to extract the Laravel, PHP, Filament, and Livewire constraints — the release note does not state them, and a branch-merge release is a plausible source of an accidental constraint change.
3. Decide storage shape and write an explicit migration (do not rely on the package's default column assumptions) — discrete lat/lng decimals are easier to index and query by bounding box; JSON is easier to extend to polygons.
4. Provision keys per environment in Google Cloud, restricted by API (Maps JS, Geocoding, Places) and by HTTP referrer/host, with budget alerts and quotas set below the billing threshold.
5. Wire the key through config from env — never hardcode, never commit.
6. Backfill: if existing records hold addresses but no coordinates, plan a one-off server-side geocode job with rate limiting and a review queue for low-confidence results, rather than resolving them lazily on page load.

Compatibility. Pin the package to an exact minor, not a caret range — the versioning signal from this release is too weak to trust ^5. Match it to the Filament major in each panel and treat Filament upgrades as a coordinated two-package change. Re-run filament:assets after every upgrade — stale published assets remain the most common cause of a silently broken map, and a release of this shape is likely to touch them. Watch for Livewire/Alpine behaviour changes; the widget and field depend on Alpine lifecycle behaviour that shifts between Livewire majors and is routinely disturbed by branch merges.

Sequencing. Prove the billing and key-restriction controls before feature work — cost and abuse controls are the actual gate, not the PHP integration. Then verify the pinned v5.0.2 build against our current Filament major in the sandbox before any production Resource is touched; do not assume the Laravel 13 headline implies backward compatibility. Pilot on one Resource with a small editor group, measure map-load and geocode volume for two weeks, and only then roll out to remaining Resources and enable the dashboard widget if the measured cost justifies it. If we are not yet on Laravel 13, there is no forcing function to adopt v5.0.2 this cycle — stay on the last verified build and fold it into the Laravel 13 upgrade.

Operational Impact

Maintenance. Low ongoing code maintenance; moderate upgrade treadmill, with a slightly higher verification burden attached to this release than to a routine patch. Budget roughly a day per Filament major upgrade to re-verify and re-publish assets, plus a shorter verification pass for each v5.x release given the weak changelog, plus periodic key rotation. The dominant long-term risk remains abandonment, though v5.0.2 is mild evidence against imminent abandonment: the maintainer is still shipping and tracking framework majors. Agree an exit posture up front — the licence permits forking and vendoring internally, and the surface area (one field, one column, one widget) is small enough that a fork is a realistic option rather than a rewrite. A branch-merge release also raises the value of forking: if we vendor, we control the merge.

Support. Community-only. There is no vendor SLA, and issue response is best-effort. That means we own an internal runbook: how to verify a key, how to read a quota error, what a broken map looks like at each layer, and who to escalate to in the cloud console. Add one entry specific to this release: how to tell a package-version regression from a key, CSP, or quota problem, since a post-merge break will present identically to a configuration fault. Treat the package as a dependency we support, not one we buy support for.

Scaling. Cost, not throughput, is the scaling axis, and this release does not move it. Every interactive map render is a billable Dynamic Maps load and every autocomplete keystroke-batch is a Places request; scaling is therefore driven by seat count × page views, not user concurrency. Two levers: use the static/non-interactive column or a plain coordinate read-only display in list views, and keep the interactive field confined to create/edit forms. The dashboard widget is the highest-cost-per-value element — rendered for every admin on every dashboard load for near-zero information gain; prefer a link-out or a count-based tile.

Failure modes. Missing or invalid key → blank/greyed map with console errors and no server-side signal; misconfigured referrer restriction → "Forbidden" watermark over the map; quota exhaustion or billing lapse → maps degrade silently mid-session; CSP or ad-blocker interference → map fails only for a subset of users, which is hard to reproduce; Livewire re-render or modal re-open → map state and marker drift, presenting as a data-loss bug rather than a UI bug. Newly relevant with this release: an undeclared breaking change in the v4 merge → field renders but fails to persist, or the widget fatals the dashboard for every admin at once, which is a whole-panel outage rather than a degraded field. Each needs an explicit detection path — client-side error surfacing into logs, an alert on 403/OVER_QUERY_LIMIT geocode responses, a form-level validation rule that coordinates must be present so a failed map cannot silently produce a record with null geometry, and a dashboard widget wrapped so a widget exception cannot take down the panel.

Ramp-up. A Laravel/Filament developer is productive in under a day; the package API is conventional and this release does not change it. The real ramp-up is Google Cloud literacy — API enablement, key restriction types, quota caps, and budget alerts — which typically sits outside the delivery team's existing skills and should be assigned to a named owner before the first deployment. Secondary ramp-up: whoever owns dependency hygiene needs enough familiarity with this package to read a branch-merge release and decide pin-versus-upgrade without waiting on the maintainer for a changelog.