Locations Api Sdk Laravel Package

Getting Started

The v1.12.1 release adds gateway token support — the headline feature you'll touch first. Treat this as the credential/authentication primitive your app uses when talking to the external gateway.

Minimal setup:

1. composer require <vendor>/<package> and confirm the service provider is auto-discovered (Laravel 9+). If not, register it in config/app.php.
2. Publish config and env scaffolding:

   php artisan vendor:publish --tag=<package>-config
   

3. Set the new gateway token in .env (e.g. GATEWAY_TOKEN=...) rather than inline in config/*.php. The package config will typically read env('GATEWAY_TOKEN').
4. Clear cached config after any env change:

   php artisan config:clear
   

First use case: grab the token once and attach it to an outbound request. Whether the package exposes a facade, a container binding, or a GatewayToken value object, the day-one flow is: resolve token → pass to your HTTP client → make the call. Look first at the package's config/<package>.php (the new token key will be there), then at its service provider to see what's bound into the container, then at the README/UPGRADING notes for the token's expected shape.

If you already have a gateway integration, wire the token in behind your existing client rather than replacing it — that keeps the blast radius of this new release small.

Implementation Patterns

Resolve, don't hardcode. Pull the token from config/container so tests and multiple environments behave predictably:

$token = config('<package>.gateway.token');
// or, if bound:
$token = app(GatewayToken::class);

Attach via an HTTP macro or middleware. For a single client, set a default header once at construction:

Http::withToken($token)->baseUrl(config('<package>.gateway.url'));

For fan-out across many call sites, wrap it in a small service or a PendingRequest macro so token handling lives in one place.

Cache the token if it's expensive to mint. The release is named "add gateway token," implying a token that may be generated, refreshed, or short-lived. If the package exposes a mint/refresh path, memoize it in the container (singleton) or Cache::remember with a TTL shorter than the token's lifetime.

Integrate with queues and long-running workers. Resolve the token per job or per request, not at boot, so a rotated token isn't held stale in a worker that's been alive for hours.

Test against a fake. Bind a static token in your test suite (or use the package's fake, if one is provided) so feature tests never hit the real gateway:

$this->app->instance(GatewayToken::class, new GatewayToken('test-token'));

Multi-tenant usage. If you serve several gateway accounts, resolve the token per tenant from your own settings table and pass it into the package — don't lean on a single global config value.

Gotchas and Tips

• Config cache is the classic trap. Adding GATEWAY_TOKEN to .env on a deployed box with config:cache in place will silently keep the old/empty value until you re-run php artisan config:cache.
• Don't commit the token. Add the env key to .env.example with a placeholder, and keep the real value in your secret manager / deploy env.
• Redact tokens in logs and exception traces. If you dump the outbound request or the container, the token can leak into logs. Wrap it in a value object with __toString() returning a masked string, or scrub it in your log processor.
• Expiry and refresh edges. If the token is time-bound, handle a 401/403 from the gateway by refreshing once and retrying — and guard against retry loops.
• Concurrency. Two workers refreshing simultaneously can invalidate each other's token if the gateway rotates on use. Use a lock (Cache::lock) around refresh if that's the behavior.
• Per-environment values. Sandbox and production tokens are usually different and not interchangeable; make sure .env files per environment reflect that.
• Extension points. If the package's token resolution is bound in the container, you can swap in your own implementation (vault-backed, tenant-aware) without forking — check the service provider for what's bind/singleton before writing custom code.
• Debugging: log the token presence and a short fingerprint (e.g. last 4 chars + length), not the value. When requests fail, first confirm the token is non-empty and the config key matches the one the release introduced — release-note-level features like this often shift the key name.