LocationService

Reference for the LocationService module: every class and function, with its full signature, parameters and return type. Real-time entity positions are served by a separate location server; this PHP module resolves and talks to that server, signs the tokens clients use to connect, and archives submitted paths to storage and the database.

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

Classes

LocationServiceApi - registers and handles the module's HTTP endpoints for tokens and path archival.
LocationServiceApiConfig - reads the API configuration values the application provides.
LocationServiceAuth - channel hashing, member permalinks and signed entity token payloads.
LocationServiceBoundary - builds an approximate bounding box around a point in meters.
LocationServiceClient - talks to a running location server over HTTP to query rectangles and entities.
LocationServiceConfig - reads the admin token and shared secret, and registers path event handlers.
LocationServiceContainerData - the resolved URLs and admin token for a running location server.
LocationServiceDatabase - resolves the running server and searches or reads entity positions through it.
LocationServiceEntityLocationData - one entity's permalink, channel code and coordinate.
LocationServicePath - registers and notifies listeners called when a path is created.
LocationServicePathData - one archived path row, with its endpoints, bounds and point count.
LocationServicePathDatabase - reads and writes archived path rows in the location_service_path table.
LocationServiceSearchResultData - one search hit: an entity permalink and its coordinate.
LocationServiceTokenError - a location server HTTP or token failure, carrying the response body.

LocationServiceApi

Registers the module's API endpoints into the ApiConfig registry and handles them: an authentication-token endpoint for the logged-in member, and a guarded admin endpoint that archives a submitted path.

Functions

AuthenticationToken AuthoriseAdmin Endpoints Path

AuthenticationToken

LocationServiceApi::AuthenticationToken(): mixed

Build the location server URL and a signed authentication token for the logged-in member. Returns null when no member is logged in.

Returns mixed An object with the location server URL and authentication token, or null.

AuthoriseAdmin

LocationServiceApi::AuthoriseAdmin(string $authorization): void

Shared-secret guard for the admin Path endpoint. Throws when the supplied token does not match the configured admin token.

Name	Type	Description
`$authorization`	`string`	The authorization token supplied by the caller.

Returns void

Endpoints

LocationServiceApi::Endpoints(): void

Returns void

Path

LocationServiceApi::Path(object $input, ApiContext $ctx): mixed

Store a submitted path chunk to storage, insert its archive row, then notify path listeners and handlers. Authorisation and input validation are handled by the endpoint config.

Name	Type	Description
`$input`	`object`	The validated endpoint input, including the entity permalink, channel hash, timestamps, point count and chunk.
`$ctx`	`ApiContext`	The API request context.

Returns mixed An object with the new path id.

LocationServiceApiConfig

Reads the API configuration values the application provides for the module.

Functions

GetTokenExpirySeconds

LocationServiceApiConfig::GetTokenExpirySeconds(): int

The configured token expiry, in seconds.

Returns int The token expiry in seconds.

LocationServiceAuth

Channel hashing, member permalinks and signed entity token payloads. Hashes are derived from the shared secret read through LocationServiceConfig.

Constants

Constant	Value	Description
`LocationServiceAuth::MEMBER_ITEM_TYPE`	`'member'`	The permalink item type used for members.

Functions

BuildTokenData ChannelHash KnownChannelCodes MemberPermalink OptionalChannelCodeFromHash

BuildTokenData

LocationServiceAuth::BuildTokenData(string $entityPermalinkString, string $channelCode, int $tokenExpirySeconds, string $moduleName = 'LocationService', string $entityType = 'member'): object

Build a signed token payload for an entity on a channel, with an expiry derived from the given number of seconds.

Name	Type	Description
`$entityPermalinkString`	`string`	The permalink string identifying the entity.
`$channelCode`	`string`	The channel code the token grants access to.
`$tokenExpirySeconds`	`int`	The number of seconds until the token expires.
`$moduleName`	`string`	The owning module name.
`$entityType`	`string`	The entity type.

Returns object The token payload, including the channel hash, expiry timestamp and signature hash.

ChannelHash

LocationServiceAuth::ChannelHash(string $channelCode): string

The 32-character hash identifying a channel code, derived from the code and the shared secret.

Name	Type	Description
`$channelCode`	`string`	The channel code to hash.

Returns string The channel hash.

KnownChannelCodes

LocationServiceAuth::KnownChannelCodes(): array

The list of channel codes the module recognises.

Returns array A list of channel code strings.

MemberPermalink

LocationServiceAuth::MemberPermalink(int $memberId): PermalinkData

The permalink for a member id, creating one if none exists yet.

Name	Type	Description
`$memberId`	`int`	The member id to resolve a permalink for.

Returns PermalinkData The member's permalink.

OptionalChannelCodeFromHash

LocationServiceAuth::OptionalChannelCodeFromHash(string $channelHash): ?string

The known channel code whose hash matches the given hash, or null when none matches.

Name	Type	Description
`$channelHash`	`string`	The channel hash to look up.

Returns ?string The matching channel code, or null.

LocationServiceBoundary

Builds an approximate axis-aligned bounding box around a point, in meters, using a local degree-per-meter approximation suitable for search radii.

Functions

RectangleAroundMeters

LocationServiceBoundary::RectangleAroundMeters(LocationCoordinateData $center, float $sizeMeters): array

An approximate bounding box of the given size, in meters, centred on a coordinate. Throws when the resulting box is degenerate.

Name	Type	Description
`$center`	`LocationCoordinateData`	The coordinate at the centre of the box.
`$sizeMeters`	`float`	The box edge length in meters.

Returns array A map with startLat, startLong, endLat and endLong.

LocationServiceClient

Talks to a running location server over HTTP to query entities within a rectangle and to read a single entity's raw record.

Functions

OptionalGetEntityRaw QueryRectangle

OptionalGetEntityRaw

LocationServiceClient::OptionalGetEntityRaw(string $serverUrl, string $adminToken, string $entityPermalinkString): ?object

Fetch the raw entity record from the server, or null when the entity is absent. Throws on a non-200 response.

Name	Type	Description
`$serverUrl`	`string`	The base URL of the location server.
`$adminToken`	`string`	The admin token sent as the authorization header.
`$entityPermalinkString`	`string`	The permalink string of the entity to fetch.

Returns ?object The raw entity object, or null.

QueryRectangle

LocationServiceClient::QueryRectangle(string $serverUrl, string $adminToken, string $channelHash, float $startLat, float $startLong, float $endLat, float $endLong): array

Query the server for entities on a channel within a rectangle. Throws on a non-200 response.

Name	Type	Description
`$serverUrl`	`string`	The base URL of the location server.
`$adminToken`	`string`	The admin token sent as the authorization header.
`$channelHash`	`string`	The channel hash to query.
`$startLat`	`float`	The southern latitude edge.
`$startLong`	`float`	The western longitude edge.
`$endLat`	`float`	The northern latitude edge.
`$endLong`	`float`	The eastern longitude edge.

Returns array A list of entities, each with a permalink string and coordinate.

LocationServiceConfig

Reads the admin token and shared secret the module needs, and registers and triggers the handlers called when a path is created.

Functions

GetAdminToken GetAdminTokenFromConfig GetSharedSecret OnPath TriggerPath

GetAdminToken

LocationServiceConfig::GetAdminToken(): string

The admin token used to authorise calls to the location server.

Returns string The admin token.

GetAdminTokenFromConfig

LocationServiceConfig::GetAdminTokenFromConfig(): string

The admin token read directly from application config; must match the location server's own token.

Returns string The admin token.

GetSharedSecret

LocationServiceConfig::GetSharedSecret(): string

The shared secret used to sign channel and entity token hashes.

Returns string The shared secret.

OnPath

LocationServiceConfig::OnPath(string $moduleName, string $entityType, callable $handler): void

Register a handler called when a path is created, filtered by module name and entity type. An empty filter matches all modules or all types.

Name	Type	Description
`$moduleName`	`string`	Filter by module name; empty matches all modules.
`$entityType`	`string`	Filter by entity type; empty matches all types.
`$handler`	`callable`	A function receiving the path id and the path data.

Returns void

TriggerPath

LocationServiceConfig::TriggerPath(int $pathId, LocationServicePathData $pathData): void

Run the registered path handlers for an inserted path. Each handler is wrapped so one failure does not disrupt the others.

Name	Type	Description
`$pathId`	`int`	The id of the inserted path.
`$pathData`	`LocationServicePathData`	The inserted path's data.

Returns void

LocationServiceContainerData

The resolved URLs and admin token for a running location server.

Properties

Name	Type	Description
`$url`	`string`	The HTTP base URL of the server.
`$websocketUrl`	`string`	The WebSocket URL of the server.
`$adminToken`	`string`	The admin token for the server.

Functions

__construct

LocationServiceContainerData::__construct(string $url, string $websocketUrl, string $adminToken)

Create the container data.

Name	Type	Description
`$url`	`string`	The HTTP base URL of the server.
`$websocketUrl`	`string`	The WebSocket URL of the server.
`$adminToken`	`string`	The admin token for the server.

LocationServiceDatabase

Resolves a running location server and searches or reads entity positions through it.

Functions

GetServiceData OptionalGetEntity SearchChannel

GetServiceData

LocationServiceDatabase::GetServiceData(): LocationServiceContainerData

Resolve a running location server and return its URLs and admin token. Throws when no server is running.

Returns LocationServiceContainerData The resolved server details.

OptionalGetEntity

LocationServiceDatabase::OptionalGetEntity(string $entityPermalinkString): ?LocationServiceEntityLocationData

Read one entity's position through the server, or null when the entity is absent or has no coordinate.

Name	Type	Description
`$entityPermalinkString`	`string`	The permalink string of the entity to read.

Returns ?LocationServiceEntityLocationData The entity location, or null.

SearchChannel

LocationServiceDatabase::SearchChannel(string $channelCode, LocationCoordinateData $location, float $sizeMeters): array

Search a channel for entities within a radius, in meters, of a coordinate.

Name	Type	Description
`$channelCode`	`string`	The channel code to search.
`$location`	`LocationCoordinateData`	The coordinate at the centre of the search.
`$sizeMeters`	`float`	The search box edge length in meters.

Returns array A list of LocationServiceSearchResultData.

LocationServiceEntityLocationData

One entity's permalink, channel code and coordinate.

Properties

Name	Type	Description
`$entityPermalinkString`	`string`	The permalink string identifying the entity.
`$channelCode`	`string`	The channel code the entity is on.
`$coordinate`	`LocationCoordinateData`	The entity's coordinate.

Functions

__construct

LocationServiceEntityLocationData::__construct(string $entityPermalinkString, string $channelCode, LocationCoordinateData $coordinate)

Create the entity location data.

Name	Type	Description
`$entityPermalinkString`	`string`	The permalink string identifying the entity.
`$channelCode`	`string`	The channel code the entity is on.
`$coordinate`	`LocationCoordinateData`	The entity's coordinate.

LocationServicePath

Registers and notifies listeners called when a path is created.

Functions

NotifyPathListeners OnPathCreated

NotifyPathListeners

LocationServicePath::NotifyPathListeners(int $pathId, string $entityCode, string $channelHash): void

Call every registered path-created listener with the given path details.

Name	Type	Description
`$pathId`	`int`	The id of the created path.
`$entityCode`	`string`	The entity code the path belongs to.
`$channelHash`	`string`	The channel hash the path was recorded on.

Returns void

OnPathCreated

LocationServicePath::OnPathCreated(callable $callback): void

Name	Type	Description
`$callback`	`callable`	A function receiving the path id, entity code and channel hash.

Returns void

LocationServicePathData

One archived path row, with its endpoints, bounds and point count.

Properties

Name	Type	Description
`$pathId`	`int`	The path id.
`$moduleName`	`string`	The owning module name.
`$entityType`	`string`	The entity type.
`$entityCode`	`string`	The entity code.
`$channelHash`	`string`	The channel hash the path was recorded on.
`$storageId`	`int`	The storage id of the path chunk.
`$startTimestamp`	`int`	The start timestamp of the path.
`$endTimestamp`	`int`	The end timestamp of the path.
`$startLatitudeMillion`	`int`	The start latitude, in millionths of a degree.
`$startLongitudeMillion`	`int`	The start longitude, in millionths of a degree.
`$endLatitudeMillion`	`int`	The end latitude, in millionths of a degree.
`$endLongitudeMillion`	`int`	The end longitude, in millionths of a degree.
`$pointCount`	`int`	The number of points in the path.
`$timestamp`	`int`	The timestamp the row was recorded.
`$date`	`string`	The recorded date.

Functions

__construct

LocationServicePathData::__construct(int $pathId, string $moduleName, string $entityType, string $entityCode, string $channelHash, int $storageId, int $startTimestamp, int $endTimestamp, int $startLatitudeMillion, int $startLongitudeMillion, int $endLatitudeMillion, int $endLongitudeMillion, int $pointCount, int $timestamp, string $date)

Create the path data.

Name	Type	Description
`$pathId`	`int`	The path id.
`$moduleName`	`string`	The owning module name.
`$entityType`	`string`	The entity type.
`$entityCode`	`string`	The entity code.
`$channelHash`	`string`	The channel hash the path was recorded on.
`$storageId`	`int`	The storage id of the path chunk.
`$startTimestamp`	`int`	The start timestamp of the path.
`$endTimestamp`	`int`	The end timestamp of the path.
`$startLatitudeMillion`	`int`	The start latitude, in millionths of a degree.
`$startLongitudeMillion`	`int`	The start longitude, in millionths of a degree.
`$endLatitudeMillion`	`int`	The end latitude, in millionths of a degree.
`$endLongitudeMillion`	`int`	The end longitude, in millionths of a degree.
`$pointCount`	`int`	The number of points in the path.
`$timestamp`	`int`	The timestamp the row was recorded.
`$date`	`string`	The recorded date.

LocationServicePathDatabase

Reads and writes archived path rows in the location_service_path table.

Functions

Count CountByEntityCodes fromRow GetById GetMaxId Insert ListOrderedByIdDesc

Count

LocationServicePathDatabase::Count(?string $moduleName = null, ?string $entityType = null, ?string $entityCode = null): int

Count archived paths, optionally filtered by module name, entity type and entity code.

Name	Type	Description
`$moduleName`	`?string`	The module name to filter by, or null.
`$entityType`	`?string`	The entity type to filter by, or null.
`$entityCode`	`?string`	The entity code to filter by, or null.

Returns int The number of matching paths.

CountByEntityCodes

LocationServicePathDatabase::CountByEntityCodes(string $moduleName, string $entityType, array $entityCodes): array

Path counts keyed by entity code, for a given module and entity type.

Name	Type	Description
`$moduleName`	`string`	The module name to count within.
`$entityType`	`string`	The entity type to count within.
`$entityCodes`	`array`	The entity codes to count for.

Returns array A map of entity code to path count.

fromRow

LocationServicePathDatabase::fromRow(object $row): LocationServicePathData

Map a database row to a LocationServicePathData object.

Name	Type	Description
`$row`	`object`	The database row to map.

Returns LocationServicePathData The mapped path data.

GetById

LocationServicePathDatabase::GetById(int $pathId): LocationServicePathData

Read one archived path row by id. Throws when there is no matching row.

Name	Type	Description
`$pathId`	`int`	The id of the path to read.

Returns LocationServicePathData The path data.

GetMaxId

LocationServicePathDatabase::GetMaxId(): int

The highest path id, or zero when the table is empty.

Returns int The highest path id, or zero.

Insert

LocationServicePathDatabase::Insert(string $moduleName, string $entityType, string $entityCode, string $channelHash, int $storageId, int $startTimestamp, int $endTimestamp, int $startLatitudeMillion, int $startLongitudeMillion, int $endLatitudeMillion, int $endLongitudeMillion, int $pointCount): int

Insert one archived path row and return its new id.

Name	Type	Description
`$moduleName`	`string`	The owning module name.
`$entityType`	`string`	The entity type.
`$entityCode`	`string`	The entity code.
`$channelHash`	`string`	The channel hash the path was recorded on.
`$storageId`	`int`	The storage id of the path chunk.
`$startTimestamp`	`int`	The start timestamp of the path.
`$endTimestamp`	`int`	The end timestamp of the path.
`$startLatitudeMillion`	`int`	The start latitude, in millionths of a degree.
`$startLongitudeMillion`	`int`	The start longitude, in millionths of a degree.
`$endLatitudeMillion`	`int`	The end latitude, in millionths of a degree.
`$endLongitudeMillion`	`int`	The end longitude, in millionths of a degree.
`$pointCount`	`int`	The number of points in the path.

Returns int The new path id.

ListOrderedByIdDesc

LocationServicePathDatabase::ListOrderedByIdDesc(int $page, int $perPage, ?string $moduleName = null, ?string $entityType = null, ?string $entityCode = null): array

A page of archived paths, newest first, with optional module, type and entity filters.

Name	Type	Description
`$page`	`int`	The 1-based page number.
`$perPage`	`int`	The number of rows per page.
`$moduleName`	`?string`	The module name to filter by, or null.
`$entityType`	`?string`	The entity type to filter by, or null.
`$entityCode`	`?string`	The entity code to filter by, or null.

Returns array A list of LocationServicePathData.

LocationServiceSearchResultData

One search hit: an entity permalink and its coordinate.

Properties

Name	Type	Description
`$entityPermalinkString`	`string`	The permalink string identifying the entity.
`$coordinate`	`LocationCoordinateData`	The entity's coordinate.

Functions

__construct

LocationServiceSearchResultData::__construct(string $entityPermalinkString, LocationCoordinateData $coordinate)

Create the search result data.

Name	Type	Description
`$entityPermalinkString`	`string`	The permalink string identifying the entity.
`$coordinate`	`LocationCoordinateData`	The entity's coordinate.

LocationServiceTokenError

A location server HTTP or token failure, such as a failed query or entity read. Extends Exception and carries the optional response body.

Properties

Name	Type	Description
`$body`	`?string`	The response body from the failed call, or null.

Functions

__construct

LocationServiceTokenError::__construct(string $message = '', int $code = 0, ?Exception $previous = null, ?string $body = null)

Create the error.

Name	Type	Description
`$message`	`string`	The error message.
`$code`	`int`	The error code.
`$previous`	`?Exception`	The previous exception, or null.
`$body`	`?string`	The response body from the failed call, or null.