Geocoder Laravel Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require toin0u/geocoder-laravel
   

   For Laravel 5.5+, auto-discovery handles the service provider registration. For older versions, add Geocoder\Laravel\Providers\GeocoderService::class to config/app.php.

2. Publish Config (if customization needed):

   php artisan vendor:publish --provider="Geocoder\Laravel\Providers\GeocoderService" --tag="config"
   

3. First Use Case: Geocode an address:

   $addresses = app('geocoder')->geocode('Los Angeles, CA')->get();
   

Implementation Patterns

Core Workflows

1. Geocoding Addresses:

   // Basic geocoding
   $addresses = app('geocoder')->geocode('1600 Amphitheatre Parkway')->get();
   
   // With locale
   $addresses = app('geocoder')->locale('fr')->geocode('Paris')->get();
   

2. Reverse Geocoding:

   $coordinates = [40.7128, -74.0060]; // [latitude, longitude]
   $addresses = app('geocoder')->reverse($coordinates)->get();
   

3. IP Geocoding:

   $addresses = app('geocoder')->geocode('8.8.8.8')->get();
   

4. Query Customization:

   use Geocoder\Query\GeocodeQuery;
   $query = GeocodeQuery::create('New York')
       ->withLocale('es')
       ->withOption('limit', 5);
   $addresses = app('geocoder')->geocodeQuery($query)->get();
   

Integration Tips

• Facade Usage:

  use Geocoder\Facades\Geocoder;
  $addresses = Geocoder::geocode('Berlin')->get();
  

• Dependency Injection:

  use Geocoder\Laravel\ProviderAndDumperAggregator as Geocoder;
  
  class AddressController {
      public function __construct(private Geocoder $geocoder) {}
  
      public function show() {
          $this->geocoder->geocode('London')->get();
      }
  }
  

• Caching:

  // Disable caching for a specific query
  $addresses = app('geocoder')->doNotCache()->geocode('Tokyo')->get();
  
  // Configure cache duration in `config/geocoder.php`
  'cache-duration' => 3600, // 1 hour
  

• Provider Chaining:

  // Use a specific provider
  $addresses = app('geocoder')->using('google_maps')->geocode('Sydney')->get();
  

• Testing:

  use Illuminate\Support\Facades\Http;
  
  Http::fake([
      'maps.googleapis.com/*' => Http::response('{"results": [...]}', 200),
  ]);
  

Gotchas and Tips

Pitfalls

1. Laravel 13 Cache Serialization:

   • If using Laravel 13, ensure cache.serializable_classes includes Geocoder model classes.
   • The package auto-registers these classes, but verify with:

     'cache' => [
         'auto_register_serializable_classes' => true,
     ]
     

   • Opt out if needed:

     'cache' => [
         'auto_register_serializable_classes' => false,
     ]
     

2. HTTPS Requirement for GoogleMaps:

   • GoogleMaps API requires HTTPS. Ensure your Laravel app uses HTTPS or set:

     'adapter' => [LaravelHttpClient::class => ['options' => ['verify' => true]]],
     

3. Cache Staleness:

   • Avoid cache-duration: 0 in production. Use a reasonable duration (e.g., 3600 for 1 hour).
   • Clear cache after config changes:

     php artisan cache:clear
     

4. Provider Failures:

   • If a provider fails (e.g., API key invalid), the chain stops. Handle errors gracefully:

     try {
         $addresses = app('geocoder')->geocode('Invalid Address')->get();
     } catch (\Geocoder\Exception\UnsupportedProviderException $e) {
         // Fallback logic
     }
     

Debugging

1. Log HTTP Requests:

   • Enable Laravel HTTP logging in config/logging.php:

     'channels' => [
         'stack' => [
             'channels' => ['single', 'geocoder'],
         ],
         'geocoder' => [
             'driver' => 'single',
             'path' => storage_path('logs/geocoder.log'),
         ],
     ],
     

2. Inspect Responses:

   • Dump raw responses for debugging:

     $response = app('geocoder')->geocode('Test')->get();
     dd($response->getCollection()->first()->getData());
     

3. Provider-Specific Issues:

   • Check provider docs (e.g., GoogleMaps Quotas) for rate limits or errors.

Extension Points

1. Custom Providers:

   • Add a new provider to the chain in config/geocoder.php:

     'providers' => [
         Chain::class => [
             GoogleMaps::class => [env('GOOGLE_MAPS_LOCALE'), env('GOOGLE_MAPS_API_KEY')],
             YourCustomProvider::class => ['your_api_key'],
         ],
     ],
     

2. Custom Adapters:

   • Replace the default HTTP adapter (e.g., for Guzzle or Symfony HTTP Client):

     'adapter' => [\Http\Client\Curl\Client::class => [null, null, [CURLOPT_PROXY => '...']]],
     

3. Custom Cache Store:

   • Use a dedicated Redis store for geocoding:

     'cache' => [
         'store' => 'geocode',
         'duration' => 3600,
     ],
     

   • Configure Redis in config/database.php and config/cache.php.

4. Event Listeners:

   • Listen for geocoding events (e.g., Geocoder\Event\Geocoded):

     use Geocoder\Event\Geocoded;
     
     event(new Geocoded($addresses));
     

Performance Tips

1. Batch Processing:

   • Use geocodeQuery() for bulk operations:

     $queries = [
         GeocodeQuery::create('Address 1'),
         GeocodeQuery::create('Address 2'),
     ];
     $results = app('geocoder')->geocodeQuery($queries)->get();
     

2. Parallel Requests:

   • For high-throughput apps, consider parallelizing requests (e.g., with spatie/async):

     use Spatie\Async\Pool;
     
     $pool = new Pool(5, function () {
         return app('geocoder')->geocode('Address')->get();
     });
     $results = $pool->then(function ($result) {
         return $result->getCollection();
     })->wait();
     

3. Local Caching Layer:

   • Combine with Laravel's cache for frequently accessed data:

     $cacheKey = 'geocode:'.md5('Los Angeles');
     $addresses = cache()->remember($cacheKey, 3600, function () {
         return app('geocoder')->geocode('Los Angeles')->get();
     });