Geoip Laravel Package

Getting Started

1. Install the package via Composer:

   composer require torann/geoip
   

2. Critical first step: Even though Laravel auto-discovery is supported, publish the config file to avoid breaking changes (especially after v3.0.8):

   php artisan vendor:publish --provider="Torann\GeoIP\GeoIPServiceProvider" --tag="config"
   

3. Configure a service in config/geoip.php. Since MaxMind’s free service is no longer bundled by default, you’ll need to either:
   • Use a paid MaxMind GeoIP2 database (set service to 'maxmind_database' and provide the path to your .mmdb file), or
   • Use a remote API (e.g., ipapi.com, ipgeolocation.io, ipinfo.io) — configure your API key in the services section.
4. Test in tinker:

   >>> GeoIP::getLocation('8.8.8.8');
   

Implementation Patterns

• Centralized IP resolution: Wrap GeoIP::getLocation() in a helper or service class to normalize location data across your app (e.g., app/helpers.php or app/Services/GeoLocation.php).
• Caching strategy: Leverage the built-in cache ('cache' => true in config) to avoid repeated lookups per request or session. For high-traffic apps, consider extending the cache_lifetime or using a dedicated cache driver.
• Middleware-based user geo-tagging: Create middleware to attach country/city data to the request/user object early in the lifecycle:

  app('geoip')->setIp($request->ip());
  $location = app('geoip')->getLocation();
  $request->merge(['country' => $location->country]);
  

• Multi-service fallback: Configure multiple services in config/geoip.php (e.g., try MaxMind DB first, fallback to IP-API). Use GeoIP::getLocation($ip, 'service_name') to target specific services when needed.
• Currency + language support: When location is available, use GeoIP::getCurrency() and GeoIP::getLanguage() for localization — ideal for e-commerce or international apps.

Gotchas and Tips

• Breaking change in v3.0.8+: If you didn’t publish the config before upgrading, the default null service will cause runtime errors. Always publish config first, especially in staging/production.
• IP resolution precedence: getLocation() defaults to $request->ip() if no IP is passed. Ensure your app correctly handles proxies/load balancers — verify trustedproxies and TrustProxies middleware if internal IPs (e.g., 192.168.x.x) are used internally.
• Database vs API trade-offs:
  • MaxMind DB: Fast, no API calls, but requires manual DB updates (use php artisan geoip:update).
  • API services: Easier setup, but subject to rate limits and latency — consider caching failures or timeouts.
• Testing tip: Mock GeoIP facade in tests to avoid network calls:

  GeoIP::shouldReceive('getLocation')->once()->andReturn((object)['country' => 'US']);
  

• Extension points:
  • Override the default GeoIP service by binding your own implementation in AppServiceProvider.
  • Extend the GeoIP class to add custom logic (e.g., IP validation, custom fallbacks) and register as a singleton.
• Debugging: Enable logging ('log_errors' => true in config) to capture failed lookups — especially useful when tracking down API key issues or rate limiting.