Google Map Display Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cethyworks/google-map-display-bundle
   

   Add the bundle to AppKernel.php (or config/bundles.php for Symfony 4+):

   new Cethyworks\GoogleMapDisplayBundle\CethyworksGoogleMapDisplayBundle(),
   

2. Configure API Key Add your Google Maps API key to config/packages/cethyworks_google_map_display.yaml:

   cethyworks_google_map_display:
       google:
           api_key: 'YOUR_GOOGLE_MAPS_API_KEY'
   

3. First Usage Inject the GoogleMapDisplayCommandHandler in a controller or service:

   use Cethyworks\GoogleMapDisplayBundle\Command\GoogleMapDisplayCommandHandler;
   
   class MapController extends AbstractController
   {
       public function showMap(GoogleMapDisplayCommandHandler $handler)
       {
           $handler->addMap('map_container_id', '1600 Amphitheatre Parkway, Mountain View, CA');
           return $this->render('map/index.html.twig');
       }
   

4. Render in Twig Ensure your template includes the bundle's JavaScript:

   {{ parent() }}
   {% block javascripts %}
       {{ parent() }}
       {{ cethyworks_google_map_display_js() }}
   {% endblock %}
   

Implementation Patterns

Common Workflows

1. Dynamic Map Rendering Use the handler in controllers to dynamically add maps based on user input:

   $handler->addMap('user_location_map', $user->address);
   $handler->addMap('business_map', $business->location);
   

2. Reusable Map Components Create a base template (map/_map.html.twig) to standardize map containers:

   <div id="{{ mapId }}" style="height: 400px; width: 100%;"></div>
   

   Include it in parent templates with dynamic IDs.

3. Batch Processing Loop through addresses to generate multiple maps:

   foreach ($locations as $location) {
       $handler->addMap("map_{$loop->index}", $location->address);
   }
   

4. Integration with Forms Use the bundle alongside GooglePlaceAutocompleteBundle for address input + map display:

   $handler->addMap('property_map', $form->get('address')->getData());
   

Advanced Patterns

1. Custom Map Options Extend the handler to pass additional Google Maps options:

   $handler->addMap('custom_map', 'Address', [
       'zoom' => 12,
       'center' => 'New York, NY',
       'mapTypeId' => 'satellite'
   ]);
   

2. Event-Driven Maps Trigger map additions in event subscribers:

   public function onLocationUpdated(LocationUpdatedEvent $event)
   {
       $this->handler->addMap('user_updated_map', $event->getNewAddress());
   }
   

3. Lazy Loading Defer map initialization until the container is visible (using Intersection Observer):

   <div id="lazy_map" data-address="{{ address }}" style="height: 400px;"></div>
   

   Extend the bundle’s JavaScript to handle lazy loading.

Gotchas and Tips

Common Pitfalls

1. API Key Restrictions

   • Ensure your Google Maps API key has Maps JavaScript API enabled.
   • Avoid hardcoding keys; use environment variables (%env(GMAPS_API_KEY)%).

2. Container ID Conflicts

   • Reuse IDs will overwrite maps. Use unique IDs (e.g., map_${entityId}).

3. JavaScript Dependencies

   • The bundle assumes jQuery is loaded. If using Symfony UX, ensure compatibility:

     {{ cethyworks_google_map_display_js() }} {# Must load AFTER jQuery #}
     

4. CORS Issues

   • If maps fail to load, verify your API key’s Referrers allow your domain.

5. Deprecated Symfony Features

   • The bundle uses AppKernel and config.yml (Symfony 3.x). For Symfony 4/5:
     • Move config to config/packages/cethyworks_google_map_display.yaml.
     • Replace AppKernel registration with config/bundles.php.

Debugging Tips

1. Check Console Errors Open browser dev tools (F12) to verify:

   • Google Maps API script loads (https://maps.googleapis.com/...).
   • No Uncaught TypeError for missing jQuery.

2. Validate Addresses Use GooglePlaceAutocompleteBundle to pre-validate addresses before rendering maps.

3. Inspect Generated HTML Search for <div id="map_id"> in the DOM to confirm containers exist.

Extension Points

1. Custom Templates Override the Twig template:

   {% extends 'CethyworksGoogleMapDisplayBundle::map.html.twig' %}
   {% block map_container %}
       <div class="custom-map" id="{{ mapId }}">...</div>
   {% endblock %}
   

2. Modify JavaScript Extend the bundle’s asset:

   // assets/js/google-map-display-ext.js
   document.addEventListener('DOMContentLoaded', function() {
       if (window.googleMapDisplay) {
           window.googleMapDisplay.options = {
               ...window.googleMapDisplay.options,
               customOption: true
           };
       }
   });
   

   Include it after the bundle’s JS in your layout.

3. Add Markers Programmatically Extend the handler to support marker data:

   $handler->addMap('map_with_markers', 'Address', [
       'markers' => [
           ['lat' => 37.422, 'lng' => -122.084, 'title' => 'Marker 1']
       ]
   ]);
   

   Requires custom JavaScript logic in the template.

4. Fallback for Missing API Key Handle missing keys gracefully in Twig:

   {% if cethyworks_google_map_display.api_key %}
       {{ cethyworks_google_map_display_js() }}
   {% else %}
       <div class="alert">Google Maps API key not configured.</div>
   {% endif %}