Laravel Geolocation Laravel Package

Getting Started

• Install with composer require adrianorosa/laravel-geolocation. Laravel's package auto-discovery should register the service provider; on older Laravel versions, check config/app.php for Adrianorosa\GeoLocation\GeoLocationServiceProvider and the accompanying facade alias (typically GeoLocation).
• Publish the config before first use: php artisan vendor:publish --tag=geolocation-config (fall back to --provider="Adrianorosa\GeoLocation\GeoLocationServiceProvider"). Open config/geolocation.php to see the lookup endpoint, timeout, and any driver/cache options.
• Read vendor/adrianorosa/laravel-geolocation/README.md and skim src/ first — this is a small package, so the service class and facade accessor are the authoritative API. Confirm the exact method names (get(), locate(), find()) and the shape of the returned object.
• First use case: enrich a request with the country/city for the caller's IP so you can localize content, prefill a form, or log the origin of a signup:

use Adrianorosa\GeoLocation\GeoLocation;

$geo = GeoLocation::get($request->ip());

$geo->country;     // "Germany"
$geo->countryCode; // "DE"
$geo->city;        // "Berlin"

Implementation Patterns

• Middleware-localization: resolve the country in a middleware, map it to a locale with a small config array, and call App::setLocale() before the controller runs. Keep the mapping in config/geolocation.php or a dedicated config/locales.php.
• Cache aggressively: geolocation calls are network-bound and the upstream free APIs are rate-limited. Wrap every lookup so repeat visitors don't trigger a new request:

$geo = Cache::remember("geo:{$ip}", now()->addDay(), fn () => GeoLocation::get($ip));

• Wrap it in your own service: bind a GeolocationService that internally calls GeoLocation::get(). That way you can swap in a local MaxMind database later without touching controllers, and you centralize the timeout/fallback logic.
• Fallback chain: private/reserved IPs (127.0.0.1, 10.x, ::1) should return null; fall back to a default country/locale rather than throwing in a middleware.
• Queueing: for non-critical enrichment (analytics, fraud scoring), dispatch a job instead of doing the lookup on the request path. Geolocation on page load is a latency tax.
• Testing with the facade: fake it rather than hit the network:

GeoLocation::shouldReceive('get')->andReturn((object) ['countryCode' => 'US']);

Or use Http::fake() if the package goes through Laravel's HTTP client.

• Consistency: normalize the result into your own DTO with typed properties (countryCode, city, lat, lng) so downstream code isn't coupled to the package's field names.

Gotchas and Tips

• Proxy IPs: $request->ip() returns the load balancer's IP unless TrustProxies is configured correctly. Check X-Forwarded-For handling before blaming the package.
• Rate limits and HTTP-only: small packages like this often lean on free public APIs (ip-api.com, ipinfo, etc.) that are rate-limited and sometimes HTTP-only on the free tier. Read the source to see which upstream is used and whether you need a paid key in config.
• Timeouts: set an explicit, short timeout in config/geolocation.php. A blocked geolocation request hanging for 5+ seconds on every page load is the classic failure mode.
• Config caching: if you run php artisan config:cache, all env() calls must live in config files. If the package calls env() at runtime, it will silently break in production — check the service constructor.
• IPv6 and reserved ranges: make sure your middleware short-circuits filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE) before lookup.
• Semver risk: with a small maintainer base and a recent release (2026-03-18), pin the version ("adrianorosa/laravel-geolocation": "^1.0") and review changelogs on upgrade. BSD-3-Clause is permissive, so forking is a viable escape hatch.
• Extension points: if the package binds an interface in its service provider, swap it out via $this->app->bind() in a custom provider. If it doesn't, the service-wrapper pattern from above is your extension point.
• Privacy: IP geolocation can be personal data under GDPR. Don't persist raw IP + location indefinitely; hash IPs for analytics and set retention in your cache TTL.
• Debugging: when a lookup returns null, log the raw response body from the upstream before the package parses it — most failures are quota exhaustion or an unexpected payload shape, not a bug in your code.