README

Leaflet integration for Symfony UX Map.

Installation

Install the bridge using Composer and Symfony Flex:

composer require symfony/ux-leaflet-map

If you're using WebpackEncore, install your assets and restart Encore (not needed if you're using AssetMapper):

npm install --force
npm run watch

Note

Alternatively, @symfony/ux-leaflet-map package can be used to install the JavaScript assets without requiring PHP.

DSN example

UX_MAP_DSN=leaflet://default

Map options

You can use the LeafletOptions class to configure your Map::

use Symfony\UX\Map\Bridge\Leaflet\LeafletOptions;
use Symfony\UX\Map\Bridge\Leaflet\Option\AttributionControlOptions;
use Symfony\UX\Map\Bridge\Leaflet\Option\ControlPosition;
use Symfony\UX\Map\Bridge\Leaflet\Option\TileLayer;
use Symfony\UX\Map\Bridge\Leaflet\Option\ZoomControlOptions;
use Symfony\UX\Map\Point;
use Symfony\UX\Map\Map;

$map = (new Map())
 ->center(new Point(48.8566, 2.3522))
 ->zoom(6);

$leafletOptions = (new LeafletOptions())
 ->tileLayer(new TileLayer(
 url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
 attribution: '© <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>',
 options: [
 'minZoom' => 5,
 'maxZoom' => 10,
 ]
 ))
 ->attributionControl(false)
 ->attributionControlOptions(new AttributionControlOptions(ControlPosition::BOTTOM_LEFT))
 ->zoomControl(false)
 ->zoomControlOptions(new ZoomControlOptions(ControlPosition::TOP_LEFT))
;

// Add the custom options to the map
$map->options($leafletOptions);

Use cases

Below are some common or advanced use cases when using a map.

Customize the marker

A common use case is to customize the marker. You can listen to the ux:map:marker:before-create event to customize the marker before it is created.

Assuming you have a map with a custom controller:

{{ ux_map(map, {'data-controller': 'my-map' }) }}

You can create a Stimulus controller to customize the markers before they are created:

// assets/controllers/my_map_controller.js
import { Controller } from '@hotwired/stimulus';

export default class extends Controller {
 connect() {
 this.element.addEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
 }

 disconnect() {
 // Always remove listeners when the controller is disconnected
 this.element.removeEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
 }

 _onMarkerBeforeCreate(event) {
 // You can access the marker definition and the Leaflet object
 // Note: `definition.bridgeOptions` is the raw options object that will be passed to the `L.marker` constructor.
 const { definition, L } = event.detail;

 // Use a custom icon for the marker
 const redIcon = L.icon({
 // Note: instead of using a hardcoded URL, you can use the `extra` parameter from `new Marker()` (PHP) and access it here with `definition.extra`.
 iconUrl: 'https://leafletjs.com/examples/custom-icons/leaf-red.png',
 shadowUrl: 'https://leafletjs.com/examples/custom-icons/leaf-shadow.png',
 iconSize: [38, 95], // size of the icon
 shadowSize: [50, 64], // size of the shadow
 iconAnchor: [22, 94], // point of the icon which will correspond to marker's location
 shadowAnchor: [4, 62], // the same for the shadow
 popupAnchor: [-3, -76], // point from which the popup should open relative to the iconAnchor
 });

 definition.bridgeOptions = {
 icon: redIcon,
 };
 }
}

Disable the default tile layer

If you need to use a custom tiles layer rendering engine that is not compatible with the L.tileLayer().addTo(map) method (e.g. Esri/esri-leaflet-vector), you can disable the default tile layer by passing tileLayer: false to the LeafletOptions:

use Symfony\UX\Map\Bridge\Leaflet\LeafletOptions;

$leafletOptions = new LeafletOptions(tileLayer: false);
// or
$leafletOptions = (new LeafletOptions())
 ->tileLayer(false);

Known issues

Unable to find leaflet/dist/leaflet.min.css file when using Webpack Encore

When using Webpack Encore with the Leaflet bridge, you may encounter the following error:

Module build failed: Module not found:
"./node_modules/.pnpm/file+vendor+symfony+ux-leaflet-map+assets_@hotwired+stimulus@3.0.0_leaflet@1.9.4/node_modules/@symfony/ux-leaflet-map/dist/map_controller.js" contains a reference to the file "leaflet/dist/leaflet.min.css".
This file can not be found, please check it for typos or update it if the file got moved.

Entrypoint app = runtime.67292354.js 488.0777101a.js app.b75294ae.css app.0975a86d.js
webpack compiled with 1 error
 ELIFECYCLE  Command failed with exit code 1.

That's because the Leaflet's Stimulus controller references the leaflet/dist/leaflet.min.css file, which exists on jsDelivr (used by the Symfony AssetMapper component), but does not in the leaflet npm package. The correct path is leaflet/dist/leaflet.css, but it is not possible to fix it because it would break compatibility with the Symfony AssetMapper component.

As a workaround, you can configure Webpack Encore to add an alias for the leaflet/dist/leaflet.min.css file:

Encore.addAliases({
 'leaflet/dist/leaflet.min.css': 'leaflet/dist/leaflet.css',
});

Resources

• Documentation
• Report issues and send Pull Requests in the main Symfony UX repository