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