How to Use Symfony UX Map

[Webmaster]

In the last topics, we have introduced Symfony Stimulus Bundle with AssetMapper. This topic shows how to use Symfony UX Map.

PHPMaker supports Custom View Tags for maps, but they are only available on List or View pages of tables. If you want to add maps in Custom Files or Dashboard Reports, Custom View Tags cannot be used. In those cases, you can use Symfony UX Map instead.

---

Note: UX Map requires Stimulus and Asset Mapper. Make sure you have them installed first, see Using Symfony Stimulus Bundle with AssetMapper for details.

Install the UX Map bundle

In your project, click Tools -> Composer packages , add the package symfony/ux-map.

UX Map ships with two renderers:

Renderer	Install Command	DSN Example
Google Maps	composer require symfony/ux-google-map	UX_MAP_DSN=google://YOUR_API_KEY@default
Leaflet	composer require symfony/ux-leaflet-map	UX_MAP_DSN=leaflet://default

Add either one package also. Generate Scripts again.

Then install the recipe, e.g.

php bin/console app:recipes:install symfony/ux-map symfony/ux-leaflet-map

• Registers UXMapBundle automatically.
• Adds default configuration in config/packages/ux_map.yaml.
• Enables the Twig helper ux_map() and Stimulus controllers.
• Stimulus initializes the maps in the browser.
• Asset Mapper handles JS and CSS assets for the renderers.

Notes:

• Google Maps requires an API key; Leaflet does not.

• Set your DSN in .env.dev.local and/or .env.prod.local:

  # Google Maps
  UX_MAP_DSN=google://YOUR_GOOGLE_MAPS_API_KEY@default
  

  or

  # Leaflet
  UX_MAP_DSN=leaflet://default
  

• The bundle reads this DSN and automatically selects the proper Stimulus controller and JS library.

• It is recommened to use CSS classes only. If you use inline styles, you need to enable 'unsafe-inline' for 'style-src-attr' in your CSP settings.

• After installation, clear cache to make sure everything is updated.

---

Create a Map in PHP

For example, in server events, you can add:

// Create a map object
$map = (new \Symfony\UX\Map\Map())
    ->center(new \Symfony\UX\Map\Point(51.5074, -0.1278)) // London
    ->zoom(10)
    ->addMarker(new \Symfony\UX\Map\Marker(
        position: new \Symfony\UX\Map\Point(51.5074, -0.1278),
        title: 'London',
        infoWindow: new \Symfony\UX\Map\InfoWindow('<p>Welcome to London!</p>')
    ));

// Pass your map(s) to view
HttpContext('ViewData', [
    'map' => $map,
]);

• Supports multiple markers, info windows, polygons, and circles (Leaflet only).

---

Render the Map in Twig

{{ ux_map(map, { style: 'height: 400px; width: 100%;' }) }}

• Outputs a <div> with data-controller="map".
• Stimulus initializes the map automatically.
• <script> tag for maps is injected once, even for multiple maps.

---

Multiple Maps

{{ ux_map(map1, { style: 'height: 300px;' }) }}
{{ ux_map(map2, { style: 'height: 300px;' }) }}

• Each <div> is initialized independently.

---

Dynamic Markers

You can also add markers, e.g.

$locations = [
    ['lat' => 48.8566, 'lng' => 2.3522, 'title' => 'Paris', 'info' => 'Hello Paris!'],
    ['lat' => 40.7128, 'lng' => -74.0060, 'title' => 'New York', 'info' => 'Hello New York!'],
];

foreach ($locations as $loc) {
    $map->addMarker(new Marker(
        position: new Point($loc['lat'], $loc['lng']),
        title: $loc['title'],
        infoWindow: new InfoWindow($loc['info'])
    ));
}

• Useful for generating maps from arrays or database results.

---

Simpler: Create Map Inline in Twig

You can also skip creating a PHP $map object and define it directly in ux_map():

{{ ux_map(
    center: [51.5074, 0.1278],
    zoom: 3,
    markers: [
        { position: [51.5074, 0.1278], title: 'London' },
        { position: [48.8566, 2.3522], title: 'Paris' },
        {
            position: [40.7128, -74.0060],
            title: 'New York',
            infoWindow: { content: 'Welcome to <b>New York</b>' }
        },
    ],
    fitBoundsToMarkers: true,
    attributes: {
        class: 'foo',
        style: 'height: 800px; width: 100%; border: 4px solid red; margin-block: 10vh;',
    }
) }}

• Perfect for quick maps or static markers.
• No PHP code.
• Works with both Leaflet and Google Maps.
• Limitations: harder to generate markers dynamically or add polygons/circles inline.

---

How UX Map Works

• PHP Map object defines center, zoom, markers, polygons.
• Twig ux_map() renders <div> with data-controller="map".
• Stimulus controller initializes the map in the browser:
  • Loads the JS library (Leaflet or Google Maps).
  • Google Maps <script> tag is injected once per page.
  • Multiple maps on the page are initialized independently.

No manual <script> or JS initialization is required.

---

Key Points

• UX Map requires Stimulus (symfony/ux-stimulus) and Asset Mapper (symfony/asset).
• Renderer (Leaflet or Google Maps) must be installed separately.
• DSN via UX_MAP_DSN allows environment-specific configuration.
• Supports multiple maps, markers, info windows, polygons, circles.
• Stimulus handles map initialization and script injection automatically.

---

Learn More

Read Symfony UX Map.