Ipstack Provider Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require geocoder-php/ipstack-provider
   

   Add the provider to your config/geocoder.php:

   'providers' => [
       'ipstack' => [
           'api_key' => env('IPSTACK_API_KEY'),
           'host' => env('IPSTACK_HOST', 'http://api.ipstack.com'),
       ],
   ],
   

2. First Use Case Fetch geocode for an IP (e.g., 1.1.1.1):

   use Geocoder\Geocoder;
   use Geocoder\Provider\Ipstack\IpstackProvider;
   
   $geocoder = new Geocoder();
   $geocoder->provider(IpstackProvider::class, ['api_key' => env('IPSTACK_API_KEY')]);
   
   $result = $geocoder->geocode('1.1.1.1');
   dd($result->first()->getCoordinates());
   

Where to Look First

• Docs: Geocoder PHP (core) + Ipstack API.
• Config: config/geocoder.php for provider-specific settings.
• Logging: Enable Geocoder\Provider\Ipstack\IpstackProvider::DEBUG for API response inspection.

Implementation Patterns

Common Workflows

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

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

2. Reverse Geocoding Convert coordinates to location:

   $result = $geocoder->reverse('40.7128', '-74.0060');
   

3. Integration with Laravel Requests Auto-detect visitor IP:

   $ip = request()->ip();
   $location = $geocoder->geocode($ip)->first();
   

Provider-Specific Tips

• Rate Limiting: Ipstack allows 10k requests/month (free tier). Cache responses aggressively:

  $geocoder->cache(new \Geocoder\Cache\Doctrine\DoctrineCache());
  

• Async Processing: Use Laravel Queues for bulk operations:

  dispatch(new GeocodeIpJob($ip));
  

Extending Functionality

• Custom Fields: Ipstack returns rich data (e.g., timezone, currency). Access via:

  $result->first()->getData()['timezone'];
  

• Fallback Providers: Combine with other providers (e.g., Nominatim) for redundancy:

  $geocoder->provider(IpstackProvider::class)->fallback('nominatim');
  

Gotchas and Tips

Pitfalls

1. API Key Leaks

   • Never hardcode IPSTACK_API_KEY in config. Use Laravel’s .env and validate:

     if (empty(env('IPSTACK_API_KEY'))) {
         throw new \RuntimeException('Ipstack API key not configured.');
     }
     

   • Tip: Use Laravel’s config/caching to avoid repeated env checks.

2. Rate Limits

   • Free tier: 10k requests/month. Monitor usage via Ipstack Dashboard.
   • Tip: Implement exponential backoff for retries:

     $geocoder->provider(IpstackProvider::class)->setRetryDelay(1000); // 1s
     

3. IPv6 Support

   • Ipstack supports IPv6, but test edge cases (e.g., ::1 for localhost).
   • Tip: Normalize IPs before geocoding:

     use Geocoder\Provider\Ipstack\IpstackProvider;
     $ip = IpstackProvider::normalizeIp($ip);
     

4. Data Inconsistencies

   • Ipstack may return null for some fields (e.g., zip in rural areas).
   • Tip: Validate responses:

     if (!$result->first()->getCoordinates()) {
         // Fallback logic
     }
     

Debugging

• Enable Debug Mode:

  $geocoder->provider(IpstackProvider::class)->setDebug(true);
  

  Logs raw API responses to storage/logs/geocoder.log.

• Common Errors:

  Error	Cause	Fix
  Invalid API key	Wrong key or expired	Regenerate key in Ipstack dashboard
  HTTP 429 Too Many Requests	Rate limit exceeded	Cache responses or upgrade plan
  Invalid IP address	Malformed IP	Validate with filter_var($ip, FILTER_VALIDATE_IP)

Extension Points

1. Custom Response Mapping Override default field mappings in a service provider:

   IpstackProvider::setFieldMappings([
       'latitude' => 'latitude',
       'longitude' => 'longitude',
       'city' => 'city',
       'custom_field' => 'ipstack_custom_field', // Map to non-standard field
   ]);
   

2. Webhook Integration Use Ipstack’s webhooks to push geocode events to your app:

   Route::post('/ipstack-webhook', function (Request $request) {
       // Process webhook payload
   });
   

3. Testing Mock the provider in tests:

   $mock = Mockery::mock(IpstackProvider::class);
   $mock->shouldReceive('geocode')
        ->once()
        ->andReturn([new Address($coordinates, $data)]);
   $geocoder->provider($mock);