Locationiq Provider Laravel Package

Technical Evaluation

Architecture fit. This is a thin, single-purpose adapter: it implements the geocoder-php/geocoder provider contract for LocationIQ's forward and reverse geocoding endpoints. Two consequences matter for a Laravel product:

• It is a plugin, not a platform. All the abstraction value comes from geocoder-php/geocoder (provider registry, Address/Coordinates value objects, query/limit/locale options). The package itself is a few hundred lines of request building and response mapping. That is a good trade — the vendor-specific surface you own is small, and the escape hatch (swap providers) is real.
• No Laravel opinion. There is no LocationIQServiceProvider, no publishable config, no facade. You write ~10–20 lines of container binding yourself. This is fine architecturally (nothing to fight, nothing to upgrade) but means the integration is your code, and the "package" does not reduce your integration ownership as much as a Laravel-native wrapper (e.g. geocoder-laravel) would.
• PSR-18 rather than hard Guzzle (since 1.4.0) is the most valuable property. It lets requests traverse your existing HTTP middleware — logging, tracing, timeouts, retry — instead of an opaque curl call. For a TPM, that is an observability dividend and removes a dependency-conflict category.

Integration feasibility. Low effort, well within a single sprint. composer require geocoder-php/geocoder geocoder-php/locationiq-provider, an API key in the environment, a singleton binding, and a small service class wrapping forward/reverse calls. No schema changes, no migrations, no background workers required for a v1. The main friction is version alignment, not code: the provider's 1.5.0 release exists specifically to support Geocoder 5, and the 1.4.x line targets Geocoder 4. You must pin the pair deliberately rather than letting ^ constraints resolve.

Technical risk. The dominant risks are vendor and maintenance, not the code:

Key questions to resolve before committing:

1. What is our committed request volume, and which LocationIQ tier and rate limit does it map to? What is the per-request cost at 3× projected growth?
2. Are we on Geocoder 4 or 5, and does any other package in the app constrain that choice?
3. Is a single-provider dependency acceptable, or does the feature require a fallback (Nominatim/Mapbox) for availability?
4. May we persist geocoded coordinates and formatted addresses, and for how long?
5. Who owns the ~200-line adapter if upstream goes quiet, and is that acceptable to the platform team?

Integration Approach

Stack fit. Laravel 9/10/11 on PHP 8.1+. The provider slots in cleanly and requires nothing of your data layer. Recommended shape:

• Bind a configured LocationIQ provider and a Geocoder instance as singletons in a dedicated GeocodingServiceProvider.
• Expose only your own interface (GeocodingService::geocode(string): ?Coordinates) to feature code. Never let controllers or models touch Geocoder\Provider\LocationIQ\* directly — that is what makes the vendor swap a one-file change later.
• Inject a PSR-18 client that is your standard outbound HTTP client (Guzzle with your middleware stack, or Laravel's HTTP client wrapped), so timeouts, retries, and tracing are uniform with the rest of the app.
• Return typed results (Coordinates, normalized address array), not raw Geocoder\Model\Address objects, at the boundary.

Migration path. Three plausible entry points:

1. Greenfield — highest leverage, lowest risk. Build behind the interface from day one, add caching and queue offload before launch.
2. From ad-hoc API calls — replace hand-rolled cURL/Guzzle calls to LocationIQ or Google. Lowest-effort win; the response mapping disappears.
3. From a vendor SDK (Google/Mapbox) — moderate effort: response semantics differ (accuracy types, component naming, normalizeCity behavior), so golden-file tests comparing old vs new output on a sample of real addresses are essential before cutover.

Compatibility notes.

• Pin geocoder-php/geocoder and the provider together; do not rely on floating constraints.
• Because 1.4.0 dropped PHP 7.3 and moved to PSR-18, any legacy Guzzle-plugin-based HTTP configuration in older services will not apply — audit that during the spike.
• If you later add a second provider, check it supports the same Geocoder major, or you will end up running two Geocoder versions.
• geocoder-laravel (the community Laravel wrapper) can host this provider if you want config publishing and a facade; evaluate whether that convenience is worth an extra dependency versus 20 lines of your own binding.

Sequencing.

1. Spike (1–2 days): install, wire, hit both endpoints with real addresses, capture quota/error behavior, verify response shape for the fields the product actually needs.
2. Interface + adapter + binding (2–3 days): your own service contract, golden-file tests against recorded HTTP fixtures, no live calls in CI.
3. Resilience (2 days): explicit timeout, bounded retry on 429/5xx, and a cache layer (Redis, TTL by query type — reverse geocode for a fixed coordinate is highly cacheable; free-text forward geocode less so).
4. Persistence + UX: store resolved coordinates on the domain model; define behavior when geocoding returns nothing (accept raw input? block? flag for manual review?).
5. Scale-out (only if needed): move to queued jobs for non-interactive paths; add a fallback provider if availability targets demand it.
6. Observability: metrics on volume, latency, cache hit rate, 429 count, empty-result rate; alert on quota burn.

Operational Impact

Maintenance. Low absolute code maintenance, non-trivial tracking maintenance. You own the wiring layer, the caching policy, the error-handling policy, and the upgrade cadence against two dependencies plus one external API. Releases are infrequent, which cuts churn but also means upstream can lag on new PHP versions — budget a small, recurring task (~1 day/quarter) to check composer outdated, PHP floor compatibility, and LocationIQ's API changelog. Because the adapter is small, "fork and maintain internally" is a credible contingency and should be written into the risk register as such rather than treated as a crisis.

Support. Two tiers, both external:

• Provider issues (auth failures, response mapping) → the geocoder-php GitHub org, low velocity. Realistically you debug this yourself; keep HTTP logging enabled in staging.
• Service issues (quota, accuracy, outages, pricing) → LocationIQ support and status page. Ensure a named owner and a paid-tier account with a support channel if the feature is revenue-bearing.

Build an internal runbook before launch: how to rotate the API key, what a 429 means and who to page, how to inspect a failed geocode, and how to fail open vs fail closed. "Fail open" (accept the user's raw address, flag it) is usually the right product default for address entry — decide this explicitly, not by accident.

Scaling. The app tier scales horizontally without thought; the quota is the only real ceiling. Key characteristics:

• One address per call — no batching in this API, so high-volume backfills (e.g. geocoding an existing address table) need throttled queue jobs and a cost estimate before you start, not after.
• Cache aggressively on reverse geocoding and on repeated forward queries (same address entered by many users is common in delivery/onboarding flows). A cache hit rate above ~40% materially changes which pricing tier you need.
• Watch that caching does not create a correctness problem if the product needs fresh results for changed addresses — key the cache on the normalized query string, not the raw input.
• Latency is network-bound (typically hundreds of ms); never call it synchronously on a page render without a timeout and a graceful fallback.

Failure modes to design for:

Ramp-up. Genuinely low: a mid-level Laravel developer is productive in half a day. The documentation is the changelog plus LocationIQ's own API docs, so plan for the team's knowledge to come from your runbook and tests, not upstream. The main ramp-up cost is not the package — it is the product and legal groundwork around it: quota sizing, PII handling, and deciding what the UI does when geocoding is uncertain or unavailable.