Gmap Bundle Laravel Package

Getting Started

• Establish whether this is even on your radar. jfsimon/gmap-bundle is a Symfony 2 bundle ([DEVEL], 19 stars, 0 dependents). It has no Laravel support, no service provider, no facade, no config/gmap.php, and no compatibility with Laravel 8+ or PHP 8.x. On a fresh Laravel app the correct first step is composer require → conflict → composer remove → move on. Your "getting started" is really "deciding how much you want to learn from it."
• Only relevant in one scenario: a legacy Symfony 2 codebase you're maintaining. If the app is already on Symfony 2 and has this in composer.json, first run composer show jfsimon/gmap-bundle to check version, constraints, and the abandoned flag. Then look, in this order, at:
  1. Resources/config/services.xml — the actual service IDs and constructor arguments.
  2. DependencyInjection/Configuration.php — the config alias (likely jfsimon_gmap) and every supported option.
  3. Twig/ — the extension, function/filter names, and how the JS is emitted.
  4. Resources/views/ — the template partials the helper renders.
• Before you invest an hour, check the emitted JavaScript. Render one map with one marker in a scratch template. If it produces GMap2, GLatLng, or GClientGeocoder you're on Google Maps JS API v2, which is retired — the bundle is functionally dead, not just unmaintained. If it emits google.maps.Map / google.maps.LatLng (v3), it's at least salvageable as a reference.
• First use case worth validating (if you're on legacy Symfony 2): the internal admin dashboard — a read-only map with a handful of markers and no customer-facing SLA. That is the only context where this bundle's value/cost ratio isn't automatically negative.
• First use case for everyone else: open the repo's Twig/ and Entity//Model/ directories and read them as a reference design for a ~200-line Laravel implementation. You'll get the domain shape (coordinate value object, map configuration object, geocoder wrapper) and skip the Symfony wiring entirely.

Implementation Patterns

• Port the domain, not the code. The bundle's real value is the abstraction shape: a Coordinate value object (lat/lng with validation), a Map configuration object (center, zoom, type, controls), and a marker list. Reimplement these as plain PHP classes under app/Support/Maps/ — no framework coupling, trivially unit-testable. This is the ~one-sprint build the PM assessment refers to.
• Config in config/gmap.php, not the controller. Mirror the bundle's YAML-driven approach with a Laravel config file: defaults (zoom, map type, controls), api_key (from .env), and named map presets. This is the config-first pattern the bundle gets right and that you should keep.
• Blade partial wrapper. Create resources/views/components/gmap.blade.php (or <x-gmap> component) that is the only place the Google Maps JS is emitted. Every view calls the component. When the API key changes, the Maps JS version bumps, or you swap providers, you edit one file.
• Controller → view model, not raw arrays. Build a MapData object (center, zoom, Marker[]) in a controller/action class and pass it to the component. This mirrors the bundle's "define in PHP, render in Twig" workflow but gives you testable seams — you can assertSee on rendered HTML and unit-test the DTO without a browser.
• Server-side geo work goes through a Geocoder contract. Define interface Geocoder { public function geocode(string $address): ?Coordinate; } and implement GoogleGeocoder with Http::get('https://maps.googleapis.com/maps/api/geocode/json', ...). Bind it in a service provider. This is the direct replacement for whatever Geocoder service the bundle wraps, but mockable in tests — which the bundle never provided.
• Multiple maps on a page. Generate a unique container ID per map in the component (map-{{ $id }}), and emit init JS keyed to that ID. The bundle's helper historically collides on id="map" — do not repeat that mistake when porting.
• Markers and info windows. Keep marker data as an array of DTOs on the server; serialize it to JSON in a data- attribute or a window.__MAPS__ script block, then have a small, untested-able-but-thin JS file read it. Do not string-interpolate JS from PHP inside Blade — that's the anti-pattern the bundle encourages and the reason it's hard to test.
• Migration workflow if you're porting a live Symfony 2 app:
  1. Snapshot current functionality with a test (render a map, assert marker count).
  2. Extract domain classes from the bundle into framework-agnostic PHP.
  3. Swap the Symfony Twig extension for a Blade component behind the same "call once per page" interface.
  4. Replace services.xml wiring with a Laravel service provider (GmapServiceProvider).
  5. Delete the Symfony dependency. Keep the domain classes.

Gotchas and Tips

• [DEVEL] is not an adjective, it's a status flag. Packagist shows it; no stability guarantees; treat any output as subject to silent change. Pin it if you must vendor it, tag it internal-only, and log the debt.
• Google Maps JS API v2 is retired. If the bundle's templates reference v2 symbols, the map renders blank or throws GMap2 is not defined in the console. This is not a config bug you can fix — it's the end of the road. Confirm with a one-line grep across the repo for GMap2|GLatLng.
• API keys and billing are on you. The Symfony-2-era bundle predates mandatory keys, billing accounts, and quota controls. Nothing in the bundle manages any of that. If you fork it, you own: key rotation, referrer restrictions, quota alarms, and privacy/consent review.
• Composer conflicts will hit first. The bundle's PHP constraint is PHP 5.x-era. In a modern Laravel app you'll see Your requirements could not be resolved. Do not attempt to force it — you'll fight the autoloader and lose.
• Twig ≠ Blade. The Twig extension (Twig/) has no analogue in Laravel. If you port the concept, write a Blade component or a @gmap directive — do not attempt to run Twig alongside Blade.
• Config alias is not documented reliably. Read DependencyInjection/Configuration.php for the true alias (jfsimon_gmap is likely), not the README. app/console config:dump-reference <alias> in the Symfony 2 app is the source of truth.
• Debugging a blank map in the legacy app: open the browser console first. Common causes, in order: (1) v2 API symbol retired, (2) map container div has height: 0 (the bundle's default CSS is often missing), (3) init JS runs before the Maps script loads — check <script> order in the rendered HTML, (4) invalid/absent API key.
• Extension points you can steal: the bundle's config tree is a good template for your config/gmap.php — nested defaults, per-map overrides, named presets. Its Map object's option handling (types, controls, zoom) is also a fine starting list of what to expose via your Blade component's props. Copy the shape, not the implementation.
• Testability is the real gap. Even if you vendor the bundle into a legacy app, you cannot write meaningful unit tests against a Twig helper that emits raw JS strings. The moment you decide you need tests (and you will), the bundle is no longer the right answer — build the thin in-house integration instead.
• Don't let "it works" tempt you into production. The absence of any downstream dependents means no one is surfacing CVEs, no one is patching Maps API deprecations, and no one is testing your specific combination of Symfony 2 + PHP version + Maps JS version. If the map surface is internal/admin, fine. If it's customer-facing, route the request to the framework-upgrade epic, not the feature backlog.