Map Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require apacz/map-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Apacz\MapBundle\ApaczMapBundle::class => ['all' => true],
   ];
   

2. Configuration Add Google Maps API key to config/packages/apacz_map.yaml:

   apacz_map:
       google_maps:
           api_key: 'YOUR_GOOGLE_MAPS_API_KEY'
   

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

   {{ render(controller('ApaczMapBundle:Default:map', {
       'width': 600,
       'height': 400,
       'center': {lat: 48.8566, lng: 2.3522},  # Paris coordinates
       'zoom': 12
   })) }}
   

Implementation Patterns

Twig Integration

• Dynamic Map Rendering Use Twig’s render function to generate maps dynamically:

  {% set mapOptions = {
      'width': userMapWidth,
      'height': userMapHeight,
      'center': {lat: userLat, lng: userLng},
      'markers': [{lat: 48.8566, lng: 2.3522, title: 'Paris'}]
  } %}
  {{ render(controller('ApaczMapBundle:Default:map', mapOptions)) }}
  

• Reusable Components Extend the bundle’s controller to add custom logic:

  // src/Controller/CustomMapController.php
  namespace App\Controller;
  
  use Apacz\MapBundle\Controller\DefaultController;
  
  class CustomMapController extends DefaultController {
      public function customMapAction($width, $height, $center) {
          $this->addMarker($center); // Custom logic
          return $this->mapAction($width, $height, $center);
      }
  }
  

Controller Workflows

• Passing Complex Data Serialize arrays/objects to JSON for Twig:

  // src/Controller/MapController.php
  public function showMapAction(Request $request) {
      $locations = [
          ['lat' => 40.7128, 'lng' => -74.0060, 'title' => 'New York'],
          ['lat' => 34.0522, 'lng' => -118.2437, 'title' => 'Los Angeles']
      ];
      return $this->render('map/map.html.twig', [
          'markers' => json_encode($locations),
          'center' => json_encode(['lat' => 37.7749, 'lng' => -122.4194])
      ]);
  }
  

• Event-Driven Maps Use JavaScript events (e.g., click) to trigger Symfony actions:

  <script>
      document.addEventListener('DOMContentLoaded', function() {
          google.maps.event.addListener(map, 'click', function(event) {
              fetch('/map/handle-click', {
                  method: 'POST',
                  body: JSON.stringify({lat: event.latLng.lat(), lng: event.latLng.lng()})
              });
          });
      });
  </script>
  

API Key Management

• Environment Variables Store the API key in .env:

  GOOGLE_MAPS_API_KEY=your_key_here
  

  Load it in config/packages/apacz_map.yaml:

  apacz_map:
      google_maps:
          api_key: '%env(GOOGLE_MAPS_API_KEY)%'
  

Gotchas and Tips

Common Pitfalls

1. API Key Restrictions

   • Ensure your Google Maps API key has Maps JavaScript API enabled in the Google Cloud Console.
   • Restricted keys (e.g., IP/referrer-based) may fail in development.

2. Twig render Caching

   • The render function caches routes by default. Clear cache after changes:

     php bin/console cache:clear
     

3. Deprecated Symfony 3

   • The bundle targets Symfony 3.x. For Symfony 4/5/6, test thoroughly or fork the bundle.

Debugging

• Console Errors Check browser console for Google Maps API errors (e.g., InvalidKey). Verify the key is correct and not revoked.

• Lat/Lng Validation Ensure coordinates are valid (e.g., lat between -90 and 90). Use:

  if ($lat < -90 || $lat > 90) {
      throw new \InvalidArgumentException('Invalid latitude');
  }
  

Extension Points

1. Custom Markers Override the Twig template (templates/ApaczMapBundle/Default/map.html.twig) to add custom icons:

   {# Add this inside the map initialization script #}
   var marker = new google.maps.Marker({
       position: {lat: {{ lat }}, lng: {{ lng }}},
       icon: '/path/to/custom-icon.png',
       title: '{{ title }}'
   });
   

2. Polyfills for Older Browsers Include a polyfill for fetch or Promise if supporting legacy browsers:

   <script src="https://cdn.jsdelivr.net/npm/promise-polyfill@8/dist/polyfill.min.js"></script>
   

3. Server-Side Geocoding Use Symfony’s HTTP client to fetch geocoding data:

   $client = new Client();
   $response = $client->get('https://maps.googleapis.com/maps/api/geocode/json', [
       'query' => [
           'address' => '1600 Amphitheatre Parkway, Mountain View',
           'key' => $this->container->getParameter('google_maps.api_key')
       ]
   ]);
   $data = json_decode($response->getContent(), true);
   

Performance Tips

• Lazy-Load Maps Load the Google Maps script dynamically to improve page load:

  <script>
      function initMap() {
          // Map initialization logic
      }
      function loadMapScript() {
          var script = document.createElement('script');
          script.src = `https://maps.googleapis.com/maps/api/js?key=${apiKey}&callback=initMap`;
          document.body.appendChild(script);
      }
      // Load after DOM is ready
      document.addEventListener('DOMContentLoaded', loadMapScript);
  </script>
  

• Static API Key For production, use a static key (not from .env) to avoid exposing it in source maps.