Per-call options

Choosing providers

You don’t need to configure every provider. To run exactly one, either set the pipeline to a single name in config or pin it per call. provider() takes one name; using() takes several, in order:

Geolocation::provider('ipinfo')->locateIp($request->ip());
Geolocation::using('maxmind_database')->locateIp($request->ip());
Geolocation::using('maxmind_database', 'ipinfo')->locateIp($request->ip());

// The scope covers the whole call it is chained to — every IP of a batch included
Geolocation::provider('maxmind_database')->batch($ips);

Scoping replaces the pipeline for that call — no other provider needs to be configured. A name that isn’t registered throws UnknownProviderException.

Overriding a credential or timeout

Tweak a provider’s credential or timeout for one call without touching global config. A credential is vendor-specific, so withToken() and withConfig() name the provider they target, and no other provider ever sees that value. withTimeout() applies to every provider:

// A credential is vendor-specific: name the provider it belongs to
Geolocation::withToken('ipinfo', 'runtime-token')->locateIp('8.8.8.8');
Geolocation::withConfig('ipinfo', ['token' => 'runtime-token', 'timeout' => 3])->locateIp('8.8.8.8');

// A timeout applies to every provider
Geolocation::withTimeout(10)->locateIp('8.8.8.8');

// e.g. a tenant's own Google key, for this one call
Geolocation::withToken('google', 'tenant-google-key')->locateAddress('Main Street 1, Springfield');

• The bundled HTTP providers read two override keys. token replaces the IPinfo token, the Google or IP2Location key, or the MaxMind web license key (the account ID stays the configured one).
• timeout replaces geolocation.timeout. The offline maxmind_database and default providers read no override.
• withConfig() merges arbitrary keys for the named provider; custom providers can read any key (see Custom providers).
• Naming a provider that isn’t registered throws UnknownProviderException.

Scope rules

• provider(), using() and every with*() return a scoped copy of the manager. The shared manager is never changed, so a scope can’t leak into later calls — even when a provider throws.
• A scope or override lasts exactly as long as the call chain it is attached to, every IP of a batch() included.
• Scoped or overridden calls bypass the cache — they neither read nor write it.

Macros

GeolocationManager is Macroable, so you can add your own methods and call them through the facade:

use RoundlyConsulting\Geolocation\GeolocationManager;

GeolocationManager::macro('countryOf', function (string $ip): ?string {
    /** @var GeolocationManager $this */
    return $this->locateIp($ip)?->countryIsoCode;
});

Geolocation::countryOf('8.8.8.8'); // "US"