Free Geoip Provider Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require geocoder-php/free-geoip-provider
   

   Add the provider to your config/geocoder.php under providers:

   'providers' => [
       'free_geoip' => [
           'host' => 'api.ipify.org', // Default, but can be overridden
           'timeout' => 5.0,
           'cache' => env('GEOCODE_CACHE', 'array'), // 'array', 'file', or 'redis'
       ],
   ],
   

2. First Use Case Resolve an IP to geolocation in a controller:

   use Geocoder\Geocoder;
   use Geocoder\ProviderManager;
   
   $providerManager = new ProviderManager();
   $geocoder = new Geocoder($providerManager, 'free_geoip');
   
   $ip = request()->ip();
   $geocode = $geocoder->geocode($ip);
   
   return response()->json($geocode->first()->getCoordinates());
   

Key Files to Review

• config/geocoder.php (Provider configuration)
• vendor/geocoder-php/free-geoip-provider/src/Provider.php (Core logic)

Implementation Patterns

Common Workflows

1. Caching Strategies

   • Array Cache (Default): Best for development.

     'cache' => 'array',
     

   • File Cache: Persistent across requests.

     'cache' => 'file',
     

   • Redis Cache: High performance for production.

     'cache' => [
         'driver' => 'redis',
         'connection' => 'cache',
     ],
     

   Tip: Cache TTL is managed by the underlying Geocoder library (default: 3600 seconds).

2. Batch Geocoding Use geocodeCollection() for multiple IPs:

   $ips = ['1.1.1.1', '8.8.8.8'];
   $results = $geocoder->geocodeCollection($ips);
   

3. Reverse Geocoding Convert coordinates to location (if the provider supports it):

   $reverse = $geocoder->reverse($coordinates);
   

4. Middleware Integration Attach geolocation data to requests:

   namespace App\Http\Middleware;
   
   use Closure;
   use Geocoder\Geocoder;
   
   class GeocodeMiddleware
   {
       protected $geocoder;
   
       public function __construct(Geocoder $geocoder)
       {
           $this->geocoder = $geocoder;
       }
   
       public function handle($request, Closure $next)
       {
           $ip = $request->ip();
           $request->merge([
               'geo' => $this->geocoder->geocode($ip)->first()
           ]);
           return $next($request);
       }
   }
   

5. Service Provider Binding Bind the geocoder in AppServiceProvider for dependency injection:

   public function register()
   {
       $this->app->singleton(Geocoder::class, function ($app) {
           $providerManager = new ProviderManager();
           $geocoder = new Geocoder($providerManager, 'free_geoip');
           return $geocoder;
       });
   }
   

Gotchas and Tips

Pitfalls

1. Rate Limiting

   • Free GeoIP providers (e.g., api.ipify.org) have strict rate limits (~1,000 requests/day).
   • Solution: Cache aggressively or use a paid provider for production.

2. IPv6 Support

   • The provider may not handle IPv6 gracefully. Test with:

     $geocode = $geocoder->geocode('2001:0db8:85a3::8a2e:0370:7334');
     

3. Cache Invalidation

   • The cache is not auto-invalidated. Manually clear if IP databases update:

     $providerManager->getProvider('free_geoip')->clearCache();
     

4. Deprecated Endpoints

   • Some free GeoIP APIs (e.g., freegeoip.net) are deprecated. Always verify the host in the provider config.

5. Time Zone Data

   • The provider may not return time zones. Use carbon/carbon to infer from coordinates:

     use Carbon\Carbon;
     $timeZone = Carbon::now()->setLatitude($lat)->setLongitude($lon)->getTimezone();
     

Debugging Tips

1. Enable Debugging Set debug: true in config/geocoder.php to log HTTP requests:

   'debug' => env('GEOCODE_DEBUG', false),
   

2. Check HTTP Status Codes Wrap geocoding in a try-catch to handle failures:

   try {
       $geocode = $geocoder->geocode($ip);
   } catch (\Geocoder\Exception\UnsupportedOperationException $e) {
       Log::error("GeoIP lookup failed: " . $e->getMessage());
   }
   

3. Validate Provider Response Inspect raw responses for malformed data:

   $provider = $providerManager->getProvider('free_geoip');
   $rawData = $provider->getData($ip);
   

Extension Points

1. Custom Provider Logic Extend the provider for additional fields (e.g., ISP data):

   namespace App\Providers;
   
   use Geocoder\Provider\FreeGeoIpProvider;
   
   class CustomFreeGeoIpProvider extends FreeGeoIpProvider
   {
       protected function parseResponse($data)
       {
           $data['isp'] = $data['isp'] ?? 'Unknown';
           return parent::parseResponse($data);
       }
   }
   

   Register it in config/geocoder.php:

   'free_geoip' => [
       'class' => App\Providers\CustomFreeGeoIpProvider::class,
       // ...
   ],
   

2. Fallback Providers Chain providers for redundancy:

   $providerManager->registerProvider('free_geoip');
   $providerManager->registerProvider('ipinfodb');
   $geocoder = new Geocoder($providerManager, ['free_geoip', 'ipinfodb']);
   

3. Environment-Specific Config Use Laravel’s config/geocoder.php to switch providers by environment:

   'providers' => [
       'free_geoip' => [
           'host' => env('GEOCODE_HOST', 'api.ipify.org'),
       ],
       'paid_geoip' => [
           'host' => env('PAID_GEOCODE_HOST', null),
           'api_key' => env('PAID_GEOCODE_KEY'),
       ],
   ],
   

   Then resolve dynamically:

   $provider = env('GEOCODE_PROVIDER', 'free_geoip');
   $geocoder = new Geocoder($providerManager, $provider);