Google Map Bundle Laravel Package

Getting Started

This package is a Symfony2 bundle, not a Laravel package — there is no service provider, no facade, and no config/*.php. Before anything else, decide whether you can actually use it: the last release was July 2015 and 0 stars/dependents means nobody is maintaining it. If you're on Laravel 5+, plan to either (a) fork it and hand-wire the services, or (b) skip it and use the underlying ivory/google-map library directly for the map objects while rendering the JS yourself.

If you're on Symfony 2.x, the flow is:

1. composer require radutopala/google-map-bundle — pin an exact version; the constraint graph expects Symfony 2.x and PHP 5.x. On anything modern, expect to resolve conflicts or vendor it.
2. Register the bundle in app/AppKernel.php (new Ivory\GoogleMapBundle\IvoryGoogleMapBundle() — verify the class name against the repo, this fork is old).
3. Add configuration:

ivory_google_map:
    api_key: "%google_maps_api_key%"
    language: en
    region: US
    async: false

Where to look first: the Ivory\GoogleMap classes it wraps (Map, Marker, InfoWindow, Coordinate, MarkerCluster) and the bundle's Twig extension/helper services. Those two are the whole API surface.

First use case — one map with a marker, built in the controller and rendered in Twig:

$map = $this->get('ivory.google_map')->createMap();
$map->setCenter(new Coordinate(48.8566, 2.3522));
$map->setZoom(12);

$marker = new Marker();
$marker->setPosition(new Coordinate(48.8566, 2.3522));
$marker->setTitle('Paris');
$map->addMarker($marker);

{{ ivory_google_map_init() }}
{{ ivory_google_map(map) }}

Implementation Patterns

• Build maps in a service, not in Twig. Inject ivory.google_map (the map builder) into a MapFactory-style service, return a configured Map, and pass it to the view. This is the only way to unit-test marker generation.
• Reusable factory methods per map type (createStoreMap(), createRouteMap()) keep options like zoom range, map type, and controls consistent across pages.
• AJAX/JS-only rendering: use the helper's JS renderer ($this->get('ivory.google_map.helper')->renderJs($map)) to return a script string for an endpoint, rather than the HTML renderer. This is the standard pattern for "filter markers without a page reload."
• Clustering: build a MarkerCluster, add all your Marker objects to it, and add the cluster to the map instead of the individual markers — this is the normal way to handle more than ~100 pins.
• Info windows: attach one InfoWindow per marker with setContent(), and keep content generation in a Twig partial rendered server-side; the library only serializes the string.
• Events: register DOM events on markers/overlays via the map's event manager (e.g. a click handler that opens an info window). Treat the handler as raw JS.
• Options as configuration: put map defaults (zoom, center, controls, map type) in config.yml/parameters and merge per-page overrides, rather than hardcoding in controllers.

Gotchas and Tips

• It is effectively abandoned. Google Maps JS API v3 has changed substantially since 2015: API keys are mandatory and billable, PanControl/RotateControl were removed, Marker is superseded by AdvancedMarkerElement, and the recommended loading strategy is the async callback= bootstrap. The generated script tag from this bundle will not match current best practice — audit and patch the script-rendering helper.
• Async loading deadlocks. With async: true, the map init must be wired to the API callback; otherwise you get google is not defined. Safest path is async: false plus explicit init helper call.
• Missing/blank API key produces a map container that never initializes, with a console error rather than a PHP exception. Add a startup assertion that the key is non-empty.
• Multiple maps on one page collide unless each Map gets a unique HTML id and JS variable name. Set these explicitly when rendering more than one map.
• Porting to Laravel means extracting the Twig extension (or calling the render helper from a Blade directive) and registering the map builder as a singleton. The ivory/google-map library itself is framework-agnostic and is the part worth keeping.
• Debugging output: serialize the map and inspect the generated JS before blaming your markers. Most "nothing renders" reports are a malformed option, a JS string that should have been raw JS, or an exception swallowed during encoding.
• Performance: encoding hundreds of markers is CPU-heavy; cache the rendered JS per map configuration where markers are static.
• Verify class names and service IDs against the tagged release, not the README — this fork predates several renames in the upstream Ivory\GoogleMap library.