GoogleMaps

Pair framework: GoogleMaps

Pair\Helpers\GoogleMaps is the browser-side entrypoint for Google Maps support in Pair.

Use it when you want Pair to:

• load /assets/PairGoogleMaps.js
• load the Google Maps JavaScript API with the correct callback
• initialize GoogleAddress inputs automatically
• keep browser API key and loader options out of ad-hoc inline scripts

In practice, this is the helper you call in views or layouts before rendering Google-enhanced address fields.

Main method

load(string $assetsPath = '/assets', ?string $browserApiKey = null, array $libraries = ['places'], array $options = []): void

Loads both Pair's frontend helper and the remote Google Maps JavaScript API.

Parameters:

• $assetsPath points to the directory that contains PairGoogleMaps.js
• $browserApiKey overrides GOOGLE_MAPS_BROWSER_API_KEY
• $libraries is normalized, deduplicated, and defaults to ['places']
• $options currently supports language, region, and version

Important runtime behavior:

• if the browser API key is missing, Pair throws a PairException
• Pair always loads PairGoogleMaps.js before the remote Google script, because the callback must exist first
• if $assetsPath is passed as assets, /assets, or another slash-variant, Pair normalizes it
• if you pass an empty library list, Pair falls back to places

Examples

Minimal setup for a standard Pair form:

use Pair\Helpers\GoogleMaps;
use Pair\Html\Form;

// Load PairGoogleMaps.js and the Google Maps JS API.
GoogleMaps::load();

$form = new Form();

echo $form->googleAddress('officeAddress')
    ->label('Office address')
    ->placeIdField('officeAddressPlaceId');

Localized loader configuration:

use Pair\Helpers\GoogleMaps;

// Ask Google for Italian labels and bias results toward Italy.
GoogleMaps::load('/assets', null, ['places'], [
    'language' => 'it',
    'region' => 'IT',
    'version' => 'weekly',
]);

Explicit browser key and custom asset directory:

use Pair\Helpers\GoogleMaps;

// Useful when the assets folder is exposed through a custom path.
GoogleMaps::load('/template/assets', 'your-browser-key', ['places']);

Re-initialize only a fragment added after the initial page load:

// Re-scan the modal body after injecting a form via AJAX.
window.PairGoogleMaps.initAll(modalBody);

Secondary methods

buildScriptUrl(string $browserApiKey, array $libraries, array $options = []): string

This internal helper is not called directly in application code. It exists to:

• sanitize the loader configuration
• build the final Google JavaScript API URL
• inject Pair's callback (PairGoogleMaps.onGoogleMapsReady)

Notes

• GOOGLE_MAPS_BROWSER_API_KEY should be browser-restricted, not your server-side Google key.
• GoogleMaps::load() is additive: it does not change normal Address inputs.
• PairGoogleMaps.js also runs on DOMContentLoaded, so fields already in the page are initialized even before the remote callback fires.

See also: GoogleAddress, GoogleMapsClient, GoogleGeocoder, GooglePlacesService, Configuration file.