Location

Reference for the Location module: geocode and reverse geocode addresses and coordinates through Google, immutable data objects for a coordinate, an address and a combined location, persistence and lookup logging, and map UI components.

This page is a pure reference. For how the framework fits together, see the Guide.

Classes

Location - geocoding helpers over LocationData, plus JSON conversion and form validation.
LocationAddress - JSON conversion for LocationAddressData.
LocationAddressData - immutable data for a postal address.
LocationAddressDatabase - store and read address rows.
LocationCoordinate - JSON conversion for LocationCoordinateData.
LocationCoordinateData - immutable latitude and longitude pair.
LocationData - immutable coordinate with an optional address.
LocationDatabase - remote geocoding, search and journey lookups via Google.
LocationLookup - geocoding via the Google Geocoding API, logging results.
LocationLookupDatabase - store and read lookup log entries.
LocationMarkerData - immutable data for a map marker.
LocationUi - map, static image, marker and input UI components.

Location

Static helper for LocationData. Geocode an address to a location, reverse geocode a coordinate, read a location's coordinate or address, convert to and from JSON, and validate a form field holding location JSON.

Functions

Coordinate FromJson FromJsonOptional Lookup OptionalAddress ReverseLookup ToJson ValidateFormField

Coordinate

Location::Coordinate(LocationData $location): LocationCoordinateData

Get the coordinate from a LocationData.

Name	Type	Description
`$location`	`LocationData`	Location data.

Returns LocationCoordinateData The coordinate data.

FromJson

Location::FromJson(stdClass $json): LocationData

Build a LocationData from a decoded JSON object holding a coordinate and an optional address.

Name	Type	Description
`$json`	`stdClass`	The decoded location JSON.

Returns LocationData The location data.

FromJsonOptional

Location::FromJsonOptional(stdClass|null $json): LocationData|null

Build a LocationData from a decoded JSON object, or null when the input is null.

Name	Type	Description
`$json`	`stdClass\|null`	The decoded location JSON, or null.

Returns LocationData|null The location data, or null.

Lookup

Location::Lookup(string $addressString): LocationData|null

Geocode an address string to a LocationData using the Google Geocoding API. Returns null when geocoding fails.

Name	Type	Description
`$addressString`	`string`	Address to geocode.

Returns LocationData|null Location data, or null if geocoding fails.

OptionalAddress

Location::OptionalAddress(LocationData $location): LocationAddressData|null

Get the optional address from a LocationData.

Name	Type	Description
`$location`	`LocationData`	Location data.

Returns LocationAddressData|null The optional address data.

ReverseLookup

Location::ReverseLookup(LocationCoordinateData $coordinate): LocationData|null

Reverse geocode a coordinate to a LocationData using the Google Geocoding API. Returns null when reverse geocoding fails.

Name	Type	Description
`$coordinate`	`LocationCoordinateData`	Coordinate to reverse geocode.

Returns LocationData|null Location data, or null if reverse geocoding fails.

ToJson

Location::ToJson(LocationData $location): stdClass

Convert a LocationData to a JSON object with its coordinate and optional address.

Name	Type	Description
`$location`	`LocationData`	The location to convert.

Returns stdClass The location as a JSON object.

ValidateFormField

Location::ValidateFormField(): callable

Return an ApiFormValidate-compatible validator for a form field holding location JSON. The returned validator accepts a JSON string or a decoded object and yields a LocationData or an error message.

Returns callable A validator for a location form field.

LocationAddress

JSON conversion helper for LocationAddressData.

Functions

FromJson FromJsonOptional ToJson

FromJson

LocationAddress::FromJson(stdClass $json): LocationAddressData

Build a LocationAddressData from a decoded JSON object.

Name	Type	Description
`$json`	`stdClass`	The decoded address JSON.

Returns LocationAddressData The address data.

FromJsonOptional

LocationAddress::FromJsonOptional(stdClass|null $json): LocationAddressData|null

Build a LocationAddressData from a decoded JSON object, or null when the input is null.

Name	Type	Description
`$json`	`stdClass\|null`	The decoded address JSON, or null.

Returns LocationAddressData|null The address data, or null.

ToJson

LocationAddress::ToJson(LocationAddressData $address): stdClass

Convert a LocationAddressData to a JSON object.

Name	Type	Description
`$address`	`LocationAddressData`	The address to convert.

Returns stdClass The address as a JSON object.

LocationAddressData

Immutable data for a postal address. Fields and constructor only.

Properties

Property	Type	Description
`$data->string`	`string`	A display string for the address (readonly).
`$data->optionalStreetNumber`	`string\|null`	Street number (readonly).
`$data->optionalStreetName`	`string\|null`	Street name or route (readonly).
`$data->optionalLocality`	`string\|null`	Locality, such as a town or city (readonly).
`$data->optionalAdministrativeAreaLevel1`	`string\|null`	First-level administrative area (readonly).
`$data->optionalAdministrativeAreaLevel2`	`string\|null`	Second-level administrative area (readonly).
`$data->optionalCountry`	`string\|null`	Country (readonly).
`$data->optionalPostalCode`	`string\|null`	Postal code (readonly).
`$data->optionalFormattedAddress`	`string\|null`	Full formatted address (readonly).

__construct

new LocationAddressData(string $string, string|null $optionalStreetNumber = null, string|null $optionalStreetName = null, string|null $optionalLocality = null, string|null $optionalAdministrativeAreaLevel1 = null, string|null $optionalAdministrativeAreaLevel2 = null, string|null $optionalCountry = null, string|null $optionalPostalCode = null, string|null $optionalFormattedAddress = null)

Create address data from a display string and optional address components.

Name	Type	Description
`$string`	`string`	A display string for the address.
`$optionalStreetNumber`	`string\|null`	Street number.
`$optionalStreetName`	`string\|null`	Street name or route.
`$optionalLocality`	`string\|null`	Locality, such as a town or city.
`$optionalAdministrativeAreaLevel1`	`string\|null`	First-level administrative area.
`$optionalAdministrativeAreaLevel2`	`string\|null`	Second-level administrative area.
`$optionalCountry`	`string\|null`	Country.
`$optionalPostalCode`	`string\|null`	Postal code.
`$optionalFormattedAddress`	`string\|null`	Full formatted address.

Returns LocationAddressData

LocationAddressDatabase

Store and read address rows in the location_address table.

Functions

Add Get GetListByIDs GetOptional

Add

LocationAddressDatabase::Add(LocationAddressData $address): int

Insert an address row and return its new id.

Name	Type	Description
`$address`	`LocationAddressData`	The address to store.

Returns int The inserted address id.

Get

LocationAddressDatabase::Get(int $addressId): LocationAddressData

Read a single address by id.

Name	Type	Description
`$addressId`	`int`	The address id.

Returns LocationAddressData The address data.

GetListByIDs

LocationAddressDatabase::GetListByIDs(array $addressIds): array

Read many addresses at once, returning a map of address id to address data.

Name	Type	Description
`$addressIds`	`array`	The address ids to read.

Returns array A map of address id to address data.

GetOptional

LocationAddressDatabase::GetOptional(int|null $addressId): LocationAddressData|null

Read a single address by id, or null when the id is null or no row is found.

Name	Type	Description
`$addressId`	`int\|null`	The address id, or null.

Returns LocationAddressData|null The address data, or null.

LocationCoordinate

JSON conversion helper for LocationCoordinateData.

Functions

FromJson ToJson

FromJson

LocationCoordinate::FromJson(stdClass $json): LocationCoordinateData

Build a LocationCoordinateData from a decoded JSON object holding latitude and longitude.

Name	Type	Description
`$json`	`stdClass`	The decoded coordinate JSON.

Returns LocationCoordinateData The coordinate data.

ToJson

LocationCoordinate::ToJson(LocationCoordinateData $coordinate): stdClass

Convert a LocationCoordinateData to a JSON object with latitude and longitude.

Name	Type	Description
`$coordinate`	`LocationCoordinateData`	The coordinate to convert.

Returns stdClass The coordinate as a JSON object.

LocationCoordinateData

Immutable latitude and longitude pair. Fields and constructor only.

Properties

Property	Type	Description
`$data->latitude`	`float`	Latitude, between -90 and 90 (readonly).
`$data->longitude`	`float`	Longitude, between -180 and 180 (readonly).

__construct

new LocationCoordinateData(float $latitude = 0, float $longitude = 0)

Create a coordinate from a latitude and longitude.

Name	Type	Description
`$latitude`	`float`	Latitude, between -90 and 90.
`$longitude`	`float`	Longitude, between -180 and 180.

Returns LocationCoordinateData

LocationData

Immutable coordinate with an optional address. Fields and constructor only.

Properties

Property	Type	Description
`$data->coordinate`	`LocationCoordinateData`	The location coordinate (readonly).
`$data->optionalAddress`	`LocationAddressData\|null`	The optional address for the location (readonly).

__construct

new LocationData(LocationCoordinateData $coordinate = new LocationCoordinateData(), LocationAddressData|null $optionalAddress = null)

Create a location from a coordinate and an optional address.

Name	Type	Description
`$coordinate`	`LocationCoordinateData`	The location coordinate.
`$optionalAddress`	`LocationAddressData\|null`	The optional address for the location.

Returns LocationData

LocationDatabase

Remote lookups via Google APIs: reverse geocode a coordinate, forward geocode an address, search addresses, and measure the driving journey between two points. Forward geocoding is logged to the lookup log.

Functions

AddressFromCoordinates AddressSearch AddressToCoordinates FromCoordinates GetDistanceAndDuration

AddressFromCoordinates

LocationDatabase::AddressFromCoordinates(LocationCoordinateData $coordinate): LocationAddressData|null

Reverse geocode a coordinate to an address via the Google Geocoding API. Returns null when the lookup fails.

Name	Type	Description
`$coordinate`	`LocationCoordinateData`	Coordinate to reverse geocode.

Returns LocationAddressData|null Address data, or null if the lookup fails.

AddressSearch

LocationDatabase::AddressSearch(string $query, int $maxResults = 5): array

Search for addresses matching a query string via the Google Geocoding API, returning up to the requested number of results. Queries shorter than three characters return an empty list.

Name	Type	Description
`$query`	`string`	Search query string.
`$maxResults`	`int`	Maximum number of results to return.

Returns array An array of matching LocationData.

AddressToCoordinates

LocationDatabase::AddressToCoordinates(string $address): LocationData|null

Forward geocode an address string to a LocationData with coordinates via the Google Geocoding API, logging the lookup. Returns null when geocoding fails.

Name	Type	Description
`$address`	`string`	Address to geocode.

Returns LocationData|null Location data, or null if geocoding fails.

FromCoordinates

LocationDatabase::FromCoordinates(LocationCoordinateData $coordinate): LocationData|null

Create a LocationData from a coordinate by reverse geocoding its address.

Name	Type	Description
`$coordinate`	`LocationCoordinateData`	Coordinate to reverse geocode.

Returns LocationData|null Location data with an address.

GetDistanceAndDuration

LocationDatabase::GetDistanceAndDuration(float $originLat, float $originLng, float $destLat, float $destLng): array

Get the driving distance and duration between two coordinates via the Google Routes computeRouteMatrix API. Throws when no route exists or the request fails.

Name	Type	Description
`$originLat`	`float`	Origin latitude.
`$originLng`	`float`	Origin longitude.
`$destLat`	`float`	Destination latitude.
`$destLng`	`float`	Destination longitude.

Returns array A pair of journey length in meters and journey time in seconds.

LocationLookup

Geocoding through the Google Geocoding API: reverse geocode a coordinate, forward geocode an address, and search addresses. Forward geocoding is logged to the lookup log.

Functions

AddressFromCoordinates AddressSearch AddressToCoordinates fromAddressString fromCoordinates

AddressFromCoordinates

LocationLookup::AddressFromCoordinates(LocationCoordinateData $coordinate): LocationAddressData|null

Reverse geocode a coordinate to an address via the Google Geocoding API. Returns null when the lookup fails.

Name	Type	Description
`$coordinate`	`LocationCoordinateData`	Coordinate to reverse geocode.

Returns LocationAddressData|null Address data, or null if the lookup fails.

AddressSearch

LocationLookup::AddressSearch(string $query, int $maxResults = 5): array

Search for addresses matching a query string via the Google Geocoding API, returning up to the requested number of results. Queries shorter than three characters return an empty list.

Name	Type	Description
`$query`	`string`	Search query string.
`$maxResults`	`int`	Maximum number of results to return.

Returns array An array of matching LocationData.

AddressToCoordinates

LocationLookup::AddressToCoordinates(string $address): LocationData|null

Forward geocode an address string to a LocationData with coordinates via the Google Geocoding API, logging the lookup. Returns null when geocoding fails.

Name	Type	Description
`$address`	`string`	Address to geocode.

Returns LocationData|null Location data, or null if geocoding fails.

fromAddressString

LocationLookup::fromAddressString(string $addressString): LocationData|null

Forward geocode an address string to a LocationData. Delegates to AddressToCoordinates.

Name	Type	Description
`$addressString`	`string`	Address to geocode.

Returns LocationData|null Location data, or null if geocoding fails.

fromCoordinates

LocationLookup::fromCoordinates(LocationCoordinateData $coordinate): LocationData|null

Build a LocationData from a coordinate by reverse geocoding its address.

Name	Type	Description
`$coordinate`	`LocationCoordinateData`	Coordinate to reverse geocode.

Returns LocationData|null Location data with an address.

LocationLookupDatabase

Store and read lookup log entries in the location_lookup_log table. Storing an entry also stores the associated address and, when enabled, the raw response JSON.

Functions

Add Get GetListByIDs

Add

LocationLookupDatabase::Add(LocationData $location, string|null $query = null, string|null $type = null, string|null $responseJson = null): int

Insert a lookup log entry and return its new id. The raw response JSON is stored only when response logging is enabled.

Name	Type	Description
`$location`	`LocationData`	The location data.
`$query`	`string\|null`	The search query, for search or geocode operations.
`$type`	`string\|null`	The lookup type, such as geocode, reverse or search.
`$responseJson`	`string\|null`	The raw response JSON, stored only when logging is enabled.

Returns int The inserted log id.

Get

LocationLookupDatabase::Get(int $logId): LocationData

Read a single lookup log entry by id as a LocationData.

Name	Type	Description
`$logId`	`int`	The log id.

Returns LocationData The location data.

GetListByIDs

LocationLookupDatabase::GetListByIDs(array $logIds): array

Read many lookup log entries at once, returning a map of log id to LocationData.

Name	Type	Description
`$logIds`	`array`	The log ids to read.

Returns array A map of log id to LocationData.

LocationMarkerData

Immutable data for a map marker. Fields and constructor only.

Properties

Property	Type	Description
`$data->coordinate`	`LocationCoordinateData`	The marker coordinate (readonly).
`$data->title`	`string\|null`	The marker title (readonly).
`$data->snippet`	`string\|null`	The marker snippet text (readonly).

__construct

new LocationMarkerData(LocationCoordinateData $coordinate, string|null $title = null, string|null $snippet = null)

Create marker data from a coordinate and optional title and snippet.

Name	Type	Description
`$coordinate`	`LocationCoordinateData`	The marker coordinate.
`$title`	`string\|null`	The marker title.
`$snippet`	`string\|null`	The marker snippet text.

Returns LocationMarkerData

LocationUi

Map UI components backed by Google Maps: an interactive map that gathers markers, a static map image, a marker registered within a map, and an address input with Places autocomplete.

Functions

Input Map Marker StaticImage

Input

LocationUi::Input(string $inputName, string $label, string|null $initialText = null, string|null $optionalStateName = null, array $optionalStateParameters = []): void

Render a location input field with Google Places autocomplete. The chosen place is stored as location JSON in a hidden field.

Name	Type	Description
`$inputName`	`string`	The name of the input field.
`$label`	`string`	The label for the input field.
`$initialText`	`string\|null`	Optional initial text to prefill.
`$optionalStateName`	`string\|null`	Optional reactive state name for a selection callback.
`$optionalStateParameters`	`array`	Optional state parameters for a selection callback.

Returns void

Map

LocationUi::Map(LocationCoordinateData $coordinate, float|null $height = null, string|null $mapId = null, callable|null $content = null): void

Render an interactive Google map centred on a coordinate. Markers added by the content callback are collected and placed on the map.

Name	Type	Description
`$coordinate`	`LocationCoordinateData`	Centre coordinate of the map.
`$height`	`float\|null`	Optional height in pixels.
`$mapId`	`string\|null`	Optional unique id for the map container.
`$content`	`callable\|null`	Callback that renders content and gathers markers.

Returns void

Marker

LocationUi::Marker(string $markerId, LocationCoordinateData $coordinate, string|null $title = null, string|null $snippet = null): void

Name	Type	Description
`$markerId`	`string`	An id for the marker.
`$coordinate`	`LocationCoordinateData`	The marker coordinate.
`$title`	`string\|null`	The marker title.
`$snippet`	`string\|null`	The marker snippet text.

Returns void

StaticImage

LocationUi::StaticImage(LocationData $location, int $width, int $height, string|null $alt = null): void

Render a static Google map image for a location at the given size.

Name	Type	Description
`$location`	`LocationData`	The location to show.
`$width`	`int`	Image width in pixels.
`$height`	`int`	Image height in pixels.
`$alt`	`string\|null`	Optional alternative text for the image.

Returns void