Google Map Helper

Using the Google Maps API V3.

Adding the helper

Either in your View class or at runtime:

$config = [
    'autoScript' => true,
];
$this->loadHelper('Geo.GoogleMap', $config);

Required (global) config:

• key

You can configure this globally using Configure (for example config/app_local.php):

'GoogleMap' => [
    'key' => 'your-api-key-here',
],

TIP

Use a non-committed config file (hence the _local suffix); keys and passwords should not be version controlled.

Possible config options are:

• api; uses v3 currently.
• zoom; uses the defaultZoom of 5 otherwise.
• type; defaults to roadmap.
• block; defaults to true, appending the generated JS to the script block.
• https; leave empty for auto-detect.
• map; multiple map options.
• staticMap; multiple static-map options.
• div; multiple div options.
• marker; multiple marker options.
• infoWindow; multiple info-window options.
• directions; multiple directions options.
• language
• geolocate
• libraries; Google Maps API libraries to load (for example places or ['places', 'geometry']).

Display a basic link to a map

$link = $this->GoogleMap->mapLink('<To Munich>!', ['to' => '<Munich>, Germany']);
// Generates: <a href="https://maps.google.com/maps?daddr=%3CMunich%3E%2C+Germany">&lt;To Munich&gt;!</a>

Display a static map

$paths = [
    [
        'path' => ['Berlin', 'Stuttgart'], // Names
        'color' => 'green',
    ],
    [
        'path' => ['44.2,11.1', '43.1,12.2', '44.3,11.3', '43.3,12.3'], // Flat array of coordinates
    ],
    [
        'path' => [['lat' => '48.1', 'lng' => '11.1'], ['lat' => '48.4', 'lng' => '11.2']],
        'color' => 'red',
        'weight' => 10,
    ],
];

$options = [
    'paths' => $this->GoogleMap->staticPaths($paths),
];
$map = $this->GoogleMap->staticMap($options);

Adding markers

$addresses = [
    [
        'address' => '44.3,11.2',
    ],
    [
        'address' => '44.2,11.1',
    ],
];
$options = ['color' => 'red', 'char' => 'C', 'shadow' => 'false'];

$markers = $this->GoogleMap->staticMarkers($addresses, $options);

$options = [
    'markers' => $markers,
];
$map = $this->GoogleMap->staticMap($options);

Display a static-map link

If you want to use JS to pop up the image:

$config = [
    'markers' => $mapMarkers,
    'escape' => false,
];
$url = $this->GoogleMap->staticMapUrl($config);
echo $this->Html->link(__('Map'), $url, ['title' => __('Map')]);

WARNING

Set 'escape' => false here to avoid double-encoding; the HtmlHelper already does the encoding.

Display a basic dynamic map

Make sure you either loaded your helper with autoScript enabled, or you manually add the apiUrl() to your scripts.

$options = [
    'zoom' => 6,
    'type' => 'R',
    'geolocate' => true,
    'div' => ['id' => 'someothers'],
    'map' => ['navOptions' => ['style' => 'SMALL'], 'typeOptions' => ['style' => 'HORIZONTAL_BAR', 'pos' => 'RIGHT_CENTER']],
];
$map = $this->GoogleMap->map($options);

// You can echo it now anywhere; it does not matter if you add markers afterwards
echo $map;

// Let's add some markers
$this->GoogleMap->addMarker(['lat' => 48.69847, 'lng' => 10.9514, 'title' => 'Marker', 'content' => 'Some Html-<b>Content</b>', 'icon' => $this->GoogleMap->iconSet('green', 'E')]);

$this->GoogleMap->addMarker(['lat' => 47.69847, 'lng' => 11.9514, 'title' => 'Marker2', 'content' => 'Some more Html-<b>Content</b>']);

$this->GoogleMap->addMarker(['lat' => 47.19847, 'lng' => 11.1514, 'title' => 'Marker3']);

// Store the final JS in an HtmlHelper script block
$this->GoogleMap->finalize();

Don't forget to output the buffered JS at the end of your page, where the other files are included (after all JS files):

echo $this->fetch('script');

This snippet is usually already in your layout.php at the end of the body tag.

Inline JS

If you need inline JS instead, call script() instead of finalize():

// Initialize
$map = $this->GoogleMap->map();

// Add markers and stuff
// $this->GoogleMap->...

// Finalize
$map .= $this->GoogleMap->script();

// Output both together
echo $map;

In general it is advised to defer JS execution by putting it at the end of the HTML (body tag), though.

Custom JS

With ->addCustom($js) you can inject any custom JS to work alongside the Google Map helper code.

Places autocomplete

The helper supports Google Places Autocomplete for address input fields. This creates an autocomplete-enabled input with hidden fields to store the selected place's latitude and longitude.

Legacy Places widget

This method generates google.maps.places.Autocomplete. Google restricts that widget to existing customers and recommends PlaceAutocompleteElement for new integrations. The helper does not wrap the new widget; follow Google’s migration guide when your project cannot use the legacy API.

Basic usage

For a project with legacy Places access, load the helper with the places library:

$this->loadHelper('Geo.GoogleMap', [
    'key' => 'your-api-key',
    'libraries' => 'places',
    'autoScript' => true,
]);

Then use the placesAutocomplete() method in your form:

echo $this->GoogleMap->placesAutocomplete('location');

This generates:

• A text input for the autocomplete.
• Hidden fields location_lat and location_lng that are populated automatically when a place is selected.

Custom options

You can customize the field and autocomplete behavior:

echo $this->GoogleMap->placesAutocomplete('address', [
    'field' => [
        'label' => 'Enter your address',
        'class' => 'form-control',
        'placeholder' => 'Start typing...',
    ],
    'lat' => '_latitude',  // Custom suffix for the lat field
    'lng' => '_longitude', // Custom suffix for the lng field
    'autocomplete' => [
        'types' => ['geocode'],
        'componentRestrictions' => ['country' => 'de'],
    ],
]);

Custom callbacks

You can add custom JavaScript to execute when a place is selected:

echo $this->GoogleMap->placesAutocomplete('location', [
    'callbacks' => [
        'placeChanged' => 'console.log("Selected: " + place.formatted_address);',
    ],
]);

The callback has access to these variables:

• place; the selected PlaceResult object.
• autocomplete; the Autocomplete instance.
• inputElement; the input DOM element.
• latField; the latitude hidden field.
• lngField; the longitude hidden field.

See also

• Leaflet helper; an open-source map alternative.
• Static map helper; JavaScript-free static map images.