- How do I install torann/geoip in a Laravel application?
- Run composer require torann/geoip, then publish the config with php artisan vendor:publish and choose a driver. The service provider and GeoIP facade are auto-discovered on modern Laravel, so no manual registration is needed. Add your provider credentials to the .env file and GeoIP::getLocation($ip) returns a Location object with country, region, city, postal code, coordinates, timezone, and currency. There are no migrations, database tables, or queue workers to set up.
- Why does torann/geoip throw an error after upgrading to version 3.0.8?
- Version 3.0.8 removed the bundled default MaxMind service for trademark and licensing reasons, so no driver is configured out of the box. If you never published the config file, the package has nothing to resolve and fails on the first lookup. The fix is to publish the config with php artisan vendor:publish and set a driver plus credentials yourself. Projects that had already published the config were not affected.
- Which Laravel and PHP versions does torann/geoip support?
- The package targets Laravel 10 through 13 on PHP 8.x, matching currently supported framework releases. Because it is a thin adapter around HTTP and local database drivers, it does not drag in heavy framework internals. Pin a specific minor version in composer.json and read the upgrade guide on Lyften.com before bumping, since the provider layer has changed in breaking ways before.
- Which geolocation services can torann/geoip use?
- It ships drivers for MaxMind (local database), ipdata.co, ipfinder.io, IP-API, and ipgeolocation.io, all normalized behind one Location value object. MaxMind's local database mode trades per-call API cost for a recurring download and refresh obligation, while HTTP services are simpler but add a network dependency and per-lookup pricing. Treat the driver choice as a data-residency, cost, and vendor-contract decision rather than a code decision.
- How do I get a visitor's location using the GeoIP facade or middleware?
- For explicit lookups call GeoIP::getLocation($ip), which returns country, region, city, postal code, latitude and longitude, timezone, and currency. The package also registers middleware that resolves the request IP and attaches the result, so controllers never touch the facade directly. Keep the facade behind your own LocationResolver interface so the package stays swappable. Behind a load balancer, configure trusted proxies so X-Forwarded-For is used instead of the edge IP.
- Can I use torann/geoip in queue workers, console commands, or scheduled tasks?
- Yes, but only by passing an IP explicitly, because there is no request object to read from in a CLI context. The middleware path is irrelevant outside HTTP, so background jobs must call the facade or your resolver with an address stored on the model or job payload. If you need geo data in jobs, capture the IP at request time rather than resolving it later.
- What happens when a lookup fails or the visitor IP is private or loopback?
- Private ranges, loopback addresses, and reserved blocks are not publicly routable, so providers return no meaningful location and the package yields empty or null fields. Failed or timed-out calls surface the same way, since the package does not retry, queue, or cache by default. Wrap the call in your own resolver with a timeout guard and an explicit fallback, such as a default locale, rather than assuming a country is always present.
- Is torann/geoip accurate enough for city-level geolocation in production?
- Country-level results are dependable across the supported drivers. City, postal code, and coordinates degrade badly on mobile carriers, CGNAT, corporate VPNs, and privacy relays, and no provider fully solves that. Treat city-level data as a soft signal for personalization or defaults, never for fraud decisions, access control, or anything legally binding, and document that accuracy ceiling in your product requirements.
- Is torann/geoip safe to use under GDPR, and what about visitor IP privacy?
- IP addresses are personal data in several jurisdictions, and the default path forwards visitor IPs to a third-party service outside your infrastructure. If your DPO has not approved outbound provider calls, the sub-processor list, and a retention policy for any cached results, engineering is blocked on review rather than code. MaxMind's local database mode can reduce outbound data sharing, but it still imposes a distribution and refresh obligation. Get legal sign-off before the first production request.
- Is torann/geoip still maintained, and what are the alternatives?
- It has roughly 2,200 GitHub stars but effectively one maintainer and no SLA, so bus factor is the real risk rather than the code itself. Alternatives include the MaxMind GeoIP2 PHP SDK used directly, or other Laravel wrappers around ipdata and ipgeolocation. Mitigate by pinning the version, publishing and owning the config file as first-party code under review, and hiding the package behind a one-method LocationResolver interface so a future swap is cheap.