Caching

Turn on caching to make repeated lookups cheap and rate-limit friendly:

GEOLOCATION_CACHE=true
GEOLOCATION_CACHE_STORE=redis      # null = the default cache store
GEOLOCATION_CACHE_TTL=86400        # seconds
GEOLOCATION_CACHE_PREFIX=geolocation

• Successful locate() and distance() results are cached for cache.ttl seconds; null results are never cached.
• batch() items go through locate(), so each IP is cached individually. Distance matrices are not cached.
• Calls scoped with using() / provider() or carrying withToken() / withTimeout() / withConfig() overrides bypass the cache entirely.
• A cache hit returns immediately and dispatches no event.
• The default fallback is never cached: it only answered because the real providers did not, so the next call asks them again.

Safe with any store

Results are stored as plain arrays and rebuilt on read, so the cache works even when your store refuses to unserialize classes (Laravel’s cache.serializable_classes set to false). A payload the package doesn’t recognise — say, one written by an older version — is treated as a miss, never an exception.

Forgetting and flushing

Drop one entry with forget() — it takes the same GeolocationQuery or DistanceQuery you looked up — or every entry at once with flushCache():

use RoundlyConsulting\Geolocation\DataTransferObjects\DistanceQuery;
use RoundlyConsulting\Geolocation\DataTransferObjects\GeolocationQuery;
use RoundlyConsulting\Geolocation\Facades\Geolocation;

Geolocation::forget(GeolocationQuery::forIp('8.8.8.8'));   // true when an entry was removed
Geolocation::forget(DistanceQuery::between($from, $to));  // distances too

Geolocation::flushCache();                                 // every lookup and distance

flushCache() works on any cache store without touching other keys: cache keys carry a generation number ({prefix}:v{generation}:locate:{hash}) and a flush moves it forward, so older entries are never read again and expire on their own TTL.