GoogleAddress

Pair framework: GoogleAddress

Pair\Html\FormControls\GoogleAddress is Pair's Google-enhanced address form control.

It keeps the visible field as a normal address input, but it can also persist Google-specific metadata in hidden fields:

• place_id
• latitude
• longitude
• JSON-encoded address components

This makes it useful when you want a classic Pair form that still stores structured location data.

When to use it

Use GoogleAddress when:

• users should type a normal address, but with Google autocomplete assistance
• the project wants to save a stable place_id for later server-side lookups
• you also need coordinates or structured components for mapping, distance, or validation logic

Do not use it when you only need a plain text address field. In that case, Address is enough.

Main behavior

• It extends Address, so the main field stays compatible with normal Pair forms.
• It adds the pairGoogleAddress CSS class and a set of data-* attributes consumed by /assets/PairGoogleMaps.js.
• The browser-side enhancement is opt-in and requires GoogleMaps::load().
• Pair clears bound metadata fields if the user manually edits the visible text after a previous Google selection.

Main methods

placeIdField(string $name, ?string $value = null): static

Configures a hidden field that stores the selected Google place_id.

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

GoogleMaps::load();

$form = new Form();

// Keep the human-readable address plus the Google place ID.
$form->googleAddress('shippingAddress')
    ->label('Shipping address')
    ->placeIdField('shippingAddressPlaceId');

coordinatesFields(string $latitudeName, string $longitudeName, float|string|null $latitudeValue = null, float|string|null $longitudeValue = null): static

Configures hidden latitude and longitude inputs.

This is one of the most common additions because it lets the application geocode once in the browser and reuse the coordinates later.

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

GoogleMaps::load();

$form = new Form();

// Save coordinates together with the visible address.
$form->googleAddress('serviceAddress')
    ->label('Service address')
    ->coordinatesFields('serviceLatitude', 'serviceLongitude');

componentsField(string $name, string|array|null $value = null): static

Configures a hidden field that stores the normalized Google address components as JSON.

If you pass an array as the initial value, Pair JSON-encodes it automatically.

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

GoogleMaps::load();

$form = new Form();

// Persist the structured Google components for later parsing.
$form->googleAddress('billingAddress')
    ->label('Billing address')
    ->componentsField('billingAddressComponents');

countries(string|array $countries): static

Restricts autocomplete suggestions to one or more ISO 3166-1 alpha-2 country codes.

types(string|array $types): static

Restricts suggestions to specific Google place types.

bounds(float $south, float $west, float $north, float $east): static

Biases autocomplete toward a rectangular viewport.

strictBounds(bool $strictBounds = true): static

When enabled, Google should only return in-bounds results.

These four methods are usually chained together:

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

GoogleMaps::load();

$form = new Form();

// Restrict the field to Italian addresses inside the Milan area.
$form->googleAddress('officeAddress')
    ->label('Office address')
    ->countries(['it'])
    ->bounds(45.4300, 9.1200, 45.5000, 9.2500)
    ->strictBounds()
    ->types(['address']);

render(): string

Renders the visible address input plus the configured hidden metadata inputs.

Most code does not call render() directly because Pair forms normally render controls through Form, but it is the method that assembles:

• the visible Address field
• the pairGoogleAddress class
• the Google-specific data-* attributes
• the optional hidden inputs for place_id, coordinates, and components

Complete form example

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

GoogleMaps::load();

$form = new Form();

// Build one field that stores both the visible address and Google metadata.
$form->googleAddress('shippingAddress')
    ->label('Shipping address')
    ->placeIdField('shippingAddressPlaceId')
    ->coordinatesFields('shippingLatitude', 'shippingLongitude')
    ->componentsField('shippingAddressComponents')
    ->countries(['it'])
    ->required();

echo $form->renderControls();

Editing an existing record with prefilled metadata:

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

GoogleMaps::load();

$form = new Form();

// Rehydrate previously saved values when editing a record.
$form->googleAddress('serviceAddress')
    ->label('Service address')
    ->value($provider->serviceAddress)
    ->placeIdField('serviceAddressPlaceId', $provider->serviceAddressPlaceId)
    ->coordinatesFields('serviceLatitude', 'serviceLongitude', $provider->serviceLatitude, $provider->serviceLongitude)
    ->componentsField('serviceAddressComponents', $provider->serviceAddressComponents);

Reacting to the browser-side selection event:

document.addEventListener('pair:google-address-selected', (event) => {
    // Use the normalized payload emitted by PairGoogleMaps.js.
    console.log(event.detail.placeId, event.detail.latitude, event.detail.longitude);
});

Secondary methods

Hidden metadata rendering

Internally, GoogleAddress renders hidden inputs only for the fields you explicitly configured. If you never call placeIdField(), coordinatesFields(), or componentsField(), no extra hidden inputs are added.

Data attribute generation

The control also writes the dataset consumed by /assets/PairGoogleMaps.js, including:

• data-google-place-id-field
• data-google-latitude-field
• data-google-longitude-field
• data-google-components-field
• data-google-countries
• data-google-types
• data-google-bounds
• data-google-strict-bounds

Notes

• Form::googleAddress() is the usual factory method used in Pair projects.
• The browser-side helper looks up bound fields by exact HTML name.
• Manual edits after a selection clear the hidden metadata fields to avoid stale place_id or coordinates.

See also: Form, FormControl, Address, GoogleMaps, GoogleGeocoder, GooglePlacesService.