Leaflet Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bmatzner/leaflet-bundle:~0.7
   php app/console assets:install web --symlink
   

   Register the bundle in app/AppKernel.php under registerBundles().

2. First Use Case: Include the bundle assets in a Twig template (e.g., base.html.twig):

   <link rel="stylesheet" href="{{ asset('bundles/bmatznerleaflet/css/leaflet.css') }}">
   <script src="{{ asset('bundles/bmatznerleaflet/js/leaflet.min.js') }}"></script>
   

   Initialize a basic map in a Twig template:

   <div id="map" style="height: 400px;"></div>
   <script>
       var map = L.map('map').setView([51.505, -0.09], 13);
       L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);
   </script>
   

Where to Look First

• Documentation: Leaflet’s official docs (v0.7.0) for API reference.
• Bundle Structure: Check vendor/bmatzner/leaflet-bundle/Resources/public/ for included assets.
• Symfony Asset Handling: Use {{ asset() }} for dynamic paths in Twig.

Implementation Patterns

Common Workflows

1. Dynamic Map Initialization: Pass map options/config via Twig variables or Twig extensions:

   {% set mapConfig = {
       center: [lat, lng],
       zoom: 13,
       layers: ['osm', 'satellite']
   } %}
   

   Render in JavaScript:

   var map = L.map('map').setView([{{ mapConfig.center[0] }}, {{ mapConfig.center[1] }}], {{ mapConfig.zoom }});
   

2. Reusable Map Components: Create a Twig macro for consistent map setups:

   {% macro leafletMap(id, center, zoom) %}
       <div id="{{ id }}" style="height: 400px;"></div>
       <script>
           var {{ id }} = L.map('{{ id }}').setView({{ center }}, {{ zoom }});
           L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo({{ id }});
       </script>
   {% endmacro %}
   

3. Integration with Symfony Forms: Use Leaflet for geolocation forms (e.g., address fields). Store coordinates in a hidden form field:

   <input type="hidden" id="map-coordinates" name="address[coordinates]">
   <script>
       map.on('click', function(e) {
           document.getElementById('map-coordinates').value = e.latlng.lat + ',' + e.latlng.lng;
       });
   </script>
   

4. Asset Versioning: Append a query string to cache-bust Leaflet assets:

   <script src="{{ asset('bundles/bmatznerleaflet/js/leaflet.min.js?v=' ~ '1.0') }}"></script>
   

Integration Tips

• Symfony Assetic: Bundle assets with Assetic for minification/concatenation.
• Webpack Encore: Replace assets:install with Encore for modern asset pipelines.
• Leaflet Plugins: Extend functionality with plugins (e.g., leaflet-markercluster) by including their JS/CSS via asset().
• Twig Extensions: Create a custom Twig extension to generate map HTML/JS dynamically.

Gotchas and Tips

Pitfalls

1. Outdated Leaflet Version:

   • The bundle ships with Leaflet v0.7.0 (released in 2013). Modern Leaflet (v1.x) has breaking changes.
   • Fix: Override assets by copying newer Leaflet files to web/bundles/bmatznerleaflet/ and update references in Twig.

2. Asset Path Assumptions:

   • The bundle assumes assets are installed in web/bundles/bmatznerleaflet/. Custom paths require manual updates to asset() calls.
   • Fix: Use --symlink in assets:install to avoid duplication.

3. IE8 Support:

   • The bundle includes leaflet.ie.css for IE8, but modern projects may not need this. Remove if unused to reduce load time.

4. No Twig Integration:

   • The bundle provides no Twig helpers or form types. Manual JS/Twig workarounds are required for dynamic maps.
   • Tip: Use Twig’s json_encode to pass PHP data to Leaflet:

     {{ dump(mapMarkers|json_encode|raw) }}
     

5. Missing Documentation:

   • The bundle lacks Symfony-specific examples (e.g., routing coordinates to controllers).
   • Tip: Refer to Symfony’s asset management docs for best practices.

Debugging

• 404 Errors: Verify assets:install ran and paths in Twig match the installed assets.
• JS Errors: Check browser console for missing dependencies (e.g., jQuery, if used by plugins).
• Console Logs: Use console.log() in Leaflet callbacks to debug events.

Extension Points

1. Custom Templates: Override bundle templates by creating BmatznerLeafletBundle::leaflet.html.twig in your theme.

2. Asset Overrides: Replace default assets by copying files to web/bundles/bmatznerleaflet/ and updating asset() paths.

3. Symfony Events: Listen to kernel.request to dynamically modify map configurations:

   $event->getRequest()->attributes->set('map_config', ['center' => [48.85, 2.35]]);
   

   Access in Twig:

   {{ dump(app.request.attributes.get('map_config')) }}
   

4. Leaflet Plugins: Include third-party plugins by extending the asset pipeline:

   <script src="{{ asset('bundles/bmatznerleaflet/js/plugins/leaflet.markercluster.js') }}"></script>
   

Performance Tips

• Lazy Loading: Load Leaflet assets only on pages needing maps (e.g., via data-turbo-track="reload" in Symfony UX Turbo).
• Compression: Use Symfony’s asset() with ?v=1.0 for cache busting and enable HTTP/2 for asset multiplexing.
• Tile Caching: Pre-render static maps for high-traffic pages (e.g., using leaflet-image).