Skip to content

symfony/ux-google-map

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Apr 15, 2025
0357b3b · Apr 15, 2025

History

54 Commits
Apr 5, 2025
Apr 15, 2025
Mar 27, 2025
Nov 20, 2024
Aug 7, 2024
Apr 15, 2025
Aug 7, 2024
Mar 9, 2025
Apr 15, 2025
Apr 15, 2025

Repository files navigation

Symfony UX Map: Google Maps

Google Maps integration for Symfony UX Map.

Installation

Install the bridge using Composer and Symfony Flex:

composer require symfony/ux-google-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-google-map package can be used to install the JavaScript assets without requiring PHP.

DSN example

UX_MAP_DSN=google://GOOGLE_MAPS_API_KEY@default

# With options
UX_MAP_DSN=google://GOOGLE_MAPS_API_KEY@default?version=weekly
UX_MAP_DSN=google://GOOGLE_MAPS_API_KEY@default?language=fr&region=FR
UX_MAP_DSN=google://GOOGLE_MAPS_API_KEY@default?libraries[]=geometry&libraries[]=places

Available options:

Option Description Default
id The id of the script tag __googleMapsScriptId
language Force language, see list of supported languages specified in the browser The user's preferred language
region Unicode region subtag identifiers compatible with ISO 3166-1
nonce Use a cryptographic nonce attribute
retries The number of script load retries 3
url Custom url to load the Google Maps API script https://maps.googleapis.com/maps/api/js
version The release channels or version numbers weekly
libraries The additional libraries to load, see list of supported libraries ['maps', 'marker'], those two libraries are always loaded

Map options

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

use Symfony\UX\Map\Bridge\Google\GoogleOptions;
use Symfony\UX\Map\Bridge\Google\Option\ControlPosition;
use Symfony\UX\Map\Bridge\Google\Option\FullscreenControlOptions;
use Symfony\UX\Map\Bridge\Google\Option\GestureHandling;
use Symfony\UX\Map\Bridge\Google\Option\MapTypeControlOptions;
use Symfony\UX\Map\Bridge\Google\Option\MapTypeControlStyle;
use Symfony\UX\Map\Bridge\Google\Option\StreetViewControlOptions;
use Symfony\UX\Map\Bridge\Google\Option\ZoomControlOptions;
use Symfony\UX\Map\Point;
use Symfony\UX\Map\Map;

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

// To configure control options and other map options:
$googleOptions = (new GoogleOptions())
    // You can skip this option if you configure "ux_map.google_maps.default_map_id"
    // in your "config/packages/ux_map.yaml".
    ->mapId('YOUR_MAP_ID') 
    
    ->gestureHandling(GestureHandling::GREEDY)
    ->backgroundColor('#f00')
    ->doubleClickZoom(true)
    ->zoomControlOptions(new ZoomControlOptions(
        position: ControlPosition::BLOCK_START_INLINE_END,
    ))
    ->mapTypeControlOptions(new MapTypeControlOptions(
        mapTypeIds: ['roadmap'],
        position: ControlPosition::INLINE_END_BLOCK_START,
        style: MapTypeControlStyle::DROPDOWN_MENU,
    ))
    ->streetViewControlOptions(new StreetViewControlOptions(
        position: ControlPosition::BLOCK_END_INLINE_START,
    ))
    ->fullscreenControlOptions(new FullscreenControlOptions(
        position: ControlPosition::INLINE_START_BLOCK_END,
    ))
;

// To disable controls:
$googleOptions = (new GoogleOptions())
    ->mapId('YOUR_MAP_ID')
    ->zoomControl(false)
    ->mapTypeControl(false)
    ->streetViewControl(false)
    ->fullscreenControl(false)
;

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

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 google object
        // Note: `definition.rawOptions` is the raw options object that will be passed to the `google.maps.Marker` constructor. 
        const { definition, google } = event.detail;

        // 1. To use a custom image for the marker 
        const beachFlagImg = document.createElement("img");
        // Note: instead of using a hardcoded URL, you can use the `extra` parameter from `new Marker()` (PHP) and access it here with `definition.extra`.
        beachFlagImg.src = "https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png";
        definition.rawOptions =  { 
            content: beachFlagImg
        }
      
        // 2. To use a custom glyph for the marker
        const pinElement = new google.maps.marker.PinElement({
            // Note: instead of using a hardcoded URL, you can use the `extra` parameter from `new Marker()` (PHP) and access it here with `definition.extra`. 
            glyph: new URL('https://maps.gstatic.com/mapfiles/place_api/icons/v2/museum_pinlet.svg'), 
            glyphColor: "white",
        });
        definition.rawOptions = {
            content: pinElement.element,
        }
    }
}

Resources