Google Map Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require egeloen/google-map-bundle
   

   Add to config/bundles.php:

   Egeloen\GoogleMapBundle\EgeloenGoogleMapBundle::class => ['all' => true],
   

2. Configuration: Publish the default config:

   php bin/console egeloen:google-map:install
   

   Update config/packages/egeloen_google_map.yaml with your Google Maps API key and other settings.

3. First Use Case: Render a basic map in a Twig template:

   {{ render(controller('EgeloenGoogleMapBundle:Default:map', {
       'mapId': 'basic-map',
       'width': 800,
       'height': 600,
       'zoom': 12,
       'center': { 'lat': 48.8584, 'lng': 2.2945 }  # Paris
   })) }}
   

Implementation Patterns

Core Workflows

1. Dynamic Map Rendering: Use the map controller action to generate maps with runtime parameters:

   // In a Symfony controller
   return $this->render('App:map:template.html.twig', [
       'map' => $this->get('egeloen_google_map.map_provider')->getMap(
           'dynamic-map',
           800,
           600,
           10,
           ['lat' => 51.5074, 'lng' => -0.1278]  // London
       )
   ]);
   

2. Markers and Overlays: Add markers via Twig:

   {{ render(controller('EgeloenGoogleMapBundle:Default:map', {
       'mapId': 'markers-map',
       'markers': [
           { 'lat': 40.7128, 'lng': -74.0060, 'infobox': 'New York' },
           { 'lat': 34.0522, 'lng': -118.2437, 'infobox': 'Los Angeles' }
       ]
   })) }}
   

3. Custom Templates: Override the default Twig template by creating templates/EgeloenGoogleMap/Default/map.html.twig in your bundle.

4. API Integration: Use the MapProvider service to generate maps programmatically:

   $map = $this->get('egeloen_google_map.map_provider')
       ->getMap('api-map', 600, 400, 8, ['lat' => 37.7749, 'lng' => -122.4194])
       ->addMarker(37.7749, -122.4194, 'San Francisco');
   

5. Lazy Loading: Enable lazy loading in config to defer map initialization:

   egeloen_google_map:
       lazy_load: true
   

Integration Tips

• Laravel-Specific: Use Symfony’s HttpFoundation components to bridge the bundle with Laravel’s routing:

  use Symfony\Component\HttpFoundation\Request;
  use Egeloen\GoogleMapBundle\Provider\MapProvider;
  
  $mapProvider = app(MapProvider::class);
  $map = $mapProvider->getMap('laravel-map', 800, 600, 12, ['lat' => 19.4326, 'lng' => -99.1332]);
  

• Asset Management: Ensure Google Maps JavaScript API is loaded before the map. Use Laravel Mix or Vite to bundle:

  // resources/js/app.js
  import '@egeloen/googlemap-bundle/dist/egeloen-googlemap-bundle.js';
  

• Environment-Specific Keys: Use Laravel’s .env for API keys:

  # config/packages/egeloen_google_map.yaml
  api_key: '%env(GOOGLE_MAPS_API_KEY)%'
  

Gotchas and Tips

Common Pitfalls

1. API Key Restrictions:

   • Ensure your Google Maps API key is enabled for Maps JavaScript API in the Google Cloud Console.
   • Restricted keys may fail silently; check browser console for Google Maps API error: RefererNotAllowedMapError.

2. CORS Issues:

   • If using a local development environment, ensure your domain is listed in the API key’s restrictions or use a wildcard (*.yourdomain.com).

3. Template Overrides:

   • Overriding templates requires the templates directory to mirror the bundle’s structure exactly. Example:

     /resources/views/vendor/EgeloenGoogleMap/Default/map.html.twig
     

4. Marker Clustering:

   • The bundle does not support marker clustering out-of-the-box. Use a library like Google Maps Marker Clusterer and extend the bundle’s JavaScript.

5. Lazy Loading Conflicts:

   • Lazy loading may interfere with dynamic map updates. Test thoroughly if modifying maps after initial render.

Debugging Tips

1. Console Errors:

   • Check the browser’s Console (F12) for errors like missing API keys or invalid coordinates.
   • Example error for invalid center:

     InvalidValueError: setCenter: not a LatLng or LatLngLiteral: in property lat: not a number
     

2. Configuration Validation:

   • Validate egeloen_google_map.yaml using:

     php bin/console debug:config egeloen_google_map
     

3. Logging:

   • Enable debug mode in config/packages/dev/egeloen_google_map.yaml:

     debug: true
     

   • Logs will appear in var/log/dev.log.

Extension Points

1. Custom Map Types: Extend the MapProvider to add custom map types (e.g., satellite, terrain):

   // src/Service/CustomMapProvider.php
   use Egeloen\GoogleMapBundle\Provider\MapProvider;
   
   class CustomMapProvider extends MapProvider {
       public function getTerrainMap($id, $width, $height, $zoom, $center) {
           return $this->getMap($id, $width, $height, $zoom, $center)
               ->setMapType('terrain');
       }
   }
   

2. Event Listeners: Subscribe to the egeloen_google_map.map.render event to modify map options:

   // src/EventListener/MapListener.php
   use Egeloen\GoogleMapBundle\Event\MapEvent;
   
   class MapListener {
       public function onMapRender(MapEvent $event) {
           $event->getMap()->setOption('disableDefaultUI', true);
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\MapListener:
           tags:
               - { name: kernel.event_listener, event: egeloen_google_map.map.render, method: onMapRender }
   

3. Polyfills for Laravel: Create a Laravel service provider to wrap the bundle’s services:

   // app/Providers/GoogleMapServiceProvider.php
   use Egeloen\GoogleMapBundle\Provider\MapProvider;
   
   class GoogleMapServiceProvider extends ServiceProvider {
       public function register() {
           $this->app->singleton('google-map', function ($app) {
               return new MapProvider(
                   $app['egeloen_google_map.options'],
                   $app['twig']
               );
           });
       }
   }
   

4. Testing: Mock the MapProvider in PHPUnit:

   $mockMapProvider = $this->createMock(MapProvider::class);
   $mockMapProvider->method('getMap')->willReturn(new Map('test-map'));
   $this->app->instance(MapProvider::class, $mockMapProvider);