Cache Provider Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require geocoder-php/cache-provider
   

   Requires geocoder-php/geocoder (≥v3.0) and a supported cache driver (e.g., predis/predis, symfony/cache).

2. Basic Usage Register the cache provider in your Geocoder configuration (e.g., config/geocoder.php):

   'cache' => [
       'provider' => \Geocoder\CacheProvider\CacheProvider::class,
       'driver' => 'predis', // or 'symfony_cache', 'array', etc.
       'options' => [
           'prefix' => 'geocoder_',
           'ttl' => 3600, // 1 hour
       ],
   ],
   

3. First Use Case Enable caching for a provider (e.g., Google Maps):

   use Geocoder\Geocoder;
   use Geocoder\Provider\GoogleMapsProvider;
   
   $geocoder = new Geocoder();
   $geocoder->registerProvider(new GoogleMapsProvider([
       'key' => 'YOUR_API_KEY',
       'cache' => true, // Enable caching
   ]));
   
   // Subsequent identical queries will use cached results
   $results = $geocoder->geocode('1600 Amphitheatre Parkway, Mountain View');
   

Implementation Patterns

Workflows

1. Hybrid Caching Strategy Combine with Geocoder\Cache\Adapter\MultipleAdapter for multi-layer caching (e.g., Redis + filesystem):

   $cache = new \Geocoder\Cache\Adapter\MultipleAdapter([
       new \Geocoder\CacheProvider\CacheProvider($redisClient),
       new \Geocoder\Cache\Adapter\FilesystemAdapter('/path/to/cache'),
   ]);
   

2. Dynamic TTL per Query Override TTL for specific queries:

   $geocoder->geocode('Paris', [
       'cache_ttl' => 86400, // 24 hours
   ]);
   

3. Cache Invalidation Clear cache for a provider or globally:

   $geocoder->getProvider('google_maps')->getCache()->clear();
   // OR
   $geocoder->getCache()->clear();
   

Integration Tips

• Laravel-Specific: Use Laravel’s cache config directly:

  'cache' => [
      'driver' => env('CACHE_DRIVER', 'redis'),
      'options' => [
          'prefix' => env('CACHE_PREFIX', 'geocoder_'),
      ],
  ],
  

• Batch Processing: Disable caching for bulk operations to avoid stale data:

  $geocoder->geocode('Address 1', ['cache' => false]);
  $geocoder->geocode('Address 2', ['cache' => false]);
  

• Fallback Logic: Pair with Geocoder\Provider\FallbackProvider to cache fallback results:

  $geocoder->registerProvider(new \Geocoder\Provider\FallbackProvider([
      'providers' => [new GoogleMapsProvider(), new OpenStreetMapProvider()],
      'cache' => true,
  ]));
  

Gotchas and Tips

Pitfalls

1. Cache Key Collisions

   • Issue: Different queries (e.g., "Paris" vs. "Paris, France") may generate identical cache keys if not properly normalized.
   • Fix: Ensure your Geocoder provider’s getCacheKey() method handles query normalization (e.g., trimming whitespace, case-insensitive matching).

2. TTL Misconfiguration

   • Issue: Setting ttl too high may serve stale data (e.g., for frequently changing addresses like event venues).
   • Tip: Use shorter TTLs (e.g., 300s) for volatile data and longer ones (e.g., 86400s) for static locations.

3. Cache Driver Dependencies

   • Issue: Some drivers (e.g., predis) require additional PHP extensions (e.g., php-redis).
   • Debug: Check for ClassNotFoundException and install missing extensions:

     pecl install redis
     

4. Memory Leaks

   • Issue: Unbounded caching of geocode results (e.g., for user-generated addresses) can bloat storage.
   • Solution: Implement a cache pruning strategy (e.g., CacheProvider::prune()) or use a size-limited adapter like symfony/cache-adapter-apcu.

Debugging

• Cache Hit/Miss Logging Extend the provider to log cache behavior:

  $geocoder->getProvider('google_maps')->setLogger(function ($message) {
      \Log::debug($message);
  });
  

• Inspect Cache Contents Dump cache keys for debugging:

  $cache = $geocoder->getProvider('google_maps')->getCache();
  $keys = $cache->getAdapter()->getKeys(); // If supported by adapter
  

Extension Points

1. Custom Cache Keys Override the cache key generation:

   $provider = new GoogleMapsProvider([
       'cache' => true,
       'cache_key_generator' => function ($query) {
           return md5(strtolower(trim($query)));
       },
   ]);
   

2. Preload Cache Warm the cache for critical locations during deployment:

   $geocoder->geocode('New York, NY'); // Preload
   $geocoder->geocode('San Francisco, CA'); // Preload
   

3. Event-Based Invalidation Listen to model events (e.g., AddressUpdated) to invalidate cache:

   use Geocoder\CacheProvider\CacheProvider;
   
   Address::updated(function ($address) {
       $cache = app(CacheProvider::class);
       $cache->delete("address_{$address->id}");
   });
   

4. Cache Provider Chaining Combine with Geocoder\Cache\Adapter\ChainAdapter for layered caching:

   $adapter = new \Geocoder\Cache\Adapter\ChainAdapter([
       new \Geocoder\CacheProvider\CacheProvider($redis),
       new \Geocoder\Cache\Adapter\FilesystemAdapter('/tmp/geocoder'),
   ]);