Download the PHP package thinwrap/location without Composer

thinwrap/location

Unified PHP facade for 21 location connectors across routing, matrix, geocoding, and isochrone — over 6 providers (Google, Mapbox, HERE, ESRI, TomTom, OSRM). Stateless. Zero vendor SDKs. Bring your own PSR-18 HTTP client.

Install

Requires PHP ≥8.2. PSR-18 HTTP client + PSR-17 factories are auto-discovered via php-http/discovery — if you don't already have one installed:

End-to-end example — 2-minute time-to-first-route

Switching providers

Change the LocationProviderId case and config DTO; the input and output shape stay identical.

Bring your own PSR-18 client

Inject any PSR-18 client through the third constructor argument on the facade — useful for tracing, retries, mocking, or proxying through symfony/http-client. The *Config DTO carries only credentials; the HTTP client is a facade-level seam.

The wrapper holds no state — no token cache, no connection pool, no retry buffer. Every operation is a single function call from input to output with one HTTP round-trip (except HERE Matrix v8, which transparently runs a submit → poll → retrieve cycle behind a single $matrix->matrix($input) call).

Error handling

Every failure surfaces as ConnectorError with a typed ProviderCode. Compose your own retry strategy from $e->providerCode and $e->cause (which carries the raw Retry-After header where the vendor sets one).

The wrapper performs no automatic retry. The Retry-After header (when present on HTTP 429) is surfaced via $e->cause['retryAfter'] (raw header string) and the parsed seconds count is woven into $e->providerMessage (…; retry after N seconds). There is no structured retryAfterSeconds field on ConnectorError.

$e->providerMessage is safe to log — known credential query params are redacted from transport-error messages. But $e->cause and $e->getPrevious() retain the raw underlying HTTP-client exception, which may embed the full request URL and headers (including live credentials); do not log them unfiltered.

_passthrough escape valve

When the normalized input doesn't expose a vendor-specific field, forward arbitrary keys via the Passthrough DTO on the operation options. The wrapper deep-merges body, shallow-merges headers and query. Consumer values win on conflict. Keys are forwarded verbatim — no casing transformation.

Each per-connector README documents its vendor-specific _passthrough examples.

Polyline utilities

All facades emit Google precision-5 encoded polyline on $result->polyline. The four public static methods on Polyline are the only encode/decode primitives exported — locked at v1.0.

Language constraints

• PHP 8.2 minimum; PHPStan level 8 expected for consumer code that uses union-typed config narrowing.
• Runs on PHP 8.2, 8.3, and 8.4 (CI matrix; Linux only at v1.0 — Windows / macOS deferred to v1.1).
• declare(strict_types=1) is required on every file in this library and recommended for consumer code.
• Zero runtime dependencies beyond psr/http-client + psr/http-factory + php-http/discovery. No vendor SDKs.
• Server-only. Most providers require server-only secrets — there is no browser story.

Public API surface (locked at v1.0)

Per-connector documentation

Each per-connector README documents auth, endpoints (regional/sandbox), narrowed input augmentations, outlier translations, error-code mappings, and _passthrough examples.

Routing (6)

Matrix (6)

Geocoding (5)

Isochrone (4)

Baseline-coverage discipline

The unified facade surface includes only features ≥90% of providers natively support. Sub-baseline fields are accessible via the Passthrough escape hatch, plus the one per-provider narrowed type that exists at v1.0 (HERE routing, src/Providers/Here/DTO/).

Migrating

From googlemaps/google-maps-services-php

From mapbox/mapbox-sdk-php (community port)

From raw HTTP / Guzzle

If you've been hand-rolling vendor HTTP calls with Guzzle, the facade collapses the boilerplate to one line per call. Error handling and retry composition stay yours.

For AI agents and contributors

• .ai/guidelines.md — contributor entry point: how to add a connector.
• .ai/ARCHITECTURE.md — 6 location-distinctive invariants + PHP rules.
• .ai/CONVENTIONS.md — naming, file layout, test patterns.

License

MIT.