Geo Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require cimus/geo-bundle
   

   (Note: Fix typo in package name: geo-bundle instead of geo-budle.)

2. Enable the Bundle: Add to config/bundles.php:

   Cimus\GeoBundle\CimusGeoBundle::class => ['all' => true],
   

3. Initialize Database: Run the update command to download and convert the IP database:

   php artisan cimus:geo:update
   

   (Assuming Laravel compatibility layer is implemented; adjust if using Symfony CLI.)

4. First Usage: Inject the service and query an IP:

   $geoData = app('cimus.geo')->search('8.8.8.8');
   // Returns array with country, region, city, etc.
   

First Use Case

Detect User Location in a Controller:

use Illuminate\Http\Request;

public function showLocation(Request $request) {
    $ip = $request->ip();
    $geo = app('cimus.geo')->search($ip);
    return view('location', ['geo' => $geo]);
}

Implementation Patterns

Core Workflows

1. IP Lookup in Middleware: Attach middleware to log or redirect based on geolocation:

   namespace App\Http\Middleware;
   
   use Closure;
   
   class GeoMiddleware {
       public function handle($request, Closure $next) {
           $geo = app('cimus.geo')->search($request->ip());
           $request->merge(['geo' => $geo]);
           return $next($request);
       }
   }
   

2. Caching Responses: Cache results for 24 hours to reduce database hits:

   $geo = Cache::remember("geo_{$ip}", 86400, function() use ($ip) {
       return app('cimus.geo')->search($ip);
   });
   

3. Bulk Lookup: Process a list of IPs (e.g., for analytics):

   $ips = ['1.1.1.1', '2.2.2.2'];
   $results = array_map(fn($ip) => app('cimus.geo')->search($ip), $ips);
   

Integration Tips

• Laravel Service Provider: Bind the Symfony service to Laravel’s container in AppServiceProvider:

  $this->app->singleton('cimus.geo', function($app) {
      return $app->make('cimus.geo');
  });
  

• Configuration: Override default settings (e.g., database path) in config/services.php:

  'geo' => [
      'database_path' => storage_path('app/geo_db'),
  ],
  

• Event-Driven Updates: Trigger updates via Laravel’s scheduler:

  // app/Console/Kernel.php
  protected function schedule(Schedule $schedule) {
      $schedule->command('cimus:geo:update')->weekly();
  }
  

Gotchas and Tips

Pitfalls

1. Database Initialization:

   • Issue: cimus:geo:update fails if the directory lacks write permissions.
   • Fix: Ensure storage/app/geo_db is writable:

     chmod -R 755 storage/app/geo_db
     

2. IP Format Sensitivity:

   • Issue: Non-standard IP formats (e.g., 256.1.1.1) may crash the lookup.
   • Fix: Validate IPs before querying:

     if (!filter_var($ip, FILTER_VALIDATE_IP)) {
         throw new \InvalidArgumentException("Invalid IP: {$ip}");
     }
     

3. Outdated Data:

   • Issue: Manual updates are required; automated cron jobs may fail silently.
   • Fix: Log command output and monitor failures:

     php artisan cimus:geo:update >> storage/logs/geo_update.log 2>&1
     

Debugging

• Empty Results:

  • Verify the database was updated (storage/app/geo_db/ipgeobase.dat exists).
  • Check for PHP warnings (e.g., E_WARNING during binary file reads).

• Performance:

  • Tip: Preload the database on boot for high-traffic apps:

    // In AppServiceProvider::boot()
    app('cimus.geo')->search('0.0.0.0'); // Force initialization
    

Extension Points

1. Custom Data Fields:

   • Extend the result array by modifying the bundle’s GeoService (if source code is available).
   • Workaround: Merge custom data post-lookup:

     $geo = app('cimus.geo')->search($ip);
     $geo['custom_field'] = $this->getCustomData($ip);
     

2. Alternative Data Sources:

   • Replace the binary database with a third-party API (e.g., IPStack) by overriding the service:

     $this->app->bind('cimus.geo', function() {
         return new CustomGeoService();
     });
     

3. Laravel Scout Integration:

   • Use geolocation for search filtering:

   $results = Model::where('country', $geo['country'])->get();