GoogleMaps - viames/pair GitHub Wiki

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.