While events.enabled is true (the default), the manager dispatches an event for every resolution:
| Event | Properties | Dispatched |
|---|---|---|
LocationResolved | query, location, provider | A provider returned a Location (provider = its pipeline name). |
DistanceResolved | query, distance, provider | A distance provider returned a Distance. |
LocationResolutionFailed | query, provider, error | A lookup ended without a location. Every provider missed: provider and error name the last unreachable provider and its redacted ProviderUnavailableException, or are both null when no provider had an answer. A provider threw: that provider and its exception, which is then rethrown. |
use Illuminate\Support\Facades\Event;
use RoundlyConsulting\Geolocation\Events\LocationResolved;
Event::listen(function (LocationResolved $event): void {
logger()->info("Resolved {$event->location->city} via {$event->provider}");
});More listeners — tracking routes and logging misses:
use RoundlyConsulting\Geolocation\Events\DistanceResolved;
use RoundlyConsulting\Geolocation\Events\LocationResolutionFailed;
Event::listen(function (DistanceResolved $event): void {
logger()->info("Route of {$event->distance->distanceInMeters} m via {$event->provider}");
});
Event::listen(function (LocationResolutionFailed $event): void {
logger()->warning('Geolocation miss', [
'ip' => $event->query->ipAddress,
'provider' => $event->provider, // the last unreachable provider, or null
'error' => $event->error?->getMessage(), // redacted — never carries credentials
]);
});- Cache hits dispatch no event — the result was already announced when it was first resolved.
- LocationResolutionFailed fires whenever a lookup ends without a location — including when every provider was unreachable. Once you configure a default location, the default provider answers whatever reaches it, so the event then fires only when a provider throws.
- Its error never carries credentials: a ProviderUnavailableException message is redacted.
- distanceMatrix() dispatches no events.
GEOLOCATION_EVENTS=false # stop dispatching all three eventsShow your open-source love
This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.
More ways to support, including cryptoBy donating, you agree to our donation terms.
Want this built into your product?
We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.