Events

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.
`DistanceResolutionFailed`	query, provider, error	distance() or distanceBetween() ended without a distance. provider and error follow the same rules as LocationResolutionFailed — a request Google refused arrives as a redacted ProviderUnavailableException naming its status.

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\DistanceResolutionFailed;
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
    ]);
});

Event::listen(function (DistanceResolutionFailed $event): void {
    logger()->warning('Distance failed', [
        'provider' => $event->provider,          // e.g. 'google', or null
        'error' => $event->error?->getMessage(), // e.g. "Geolocation provider [google] is unavailable: PERMISSION_DENIED: …"
    ]);
});

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.
DistanceResolutionFailed is its distance counterpart: it fires whenever distance() or distanceBetween() ends without a distance, naming the provider and error the same way — a key without the Routes API enabled shows up here.
Their error never carries credentials: a ProviderUnavailableException message is redacted.
distanceMatrix() dispatches no events.

GEOLOCATION_EVENTS=false   # stop dispatching all four events

Show 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 crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

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.

Get a quote in 48 hours Browse all packages