Adibox Cache Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require adibox/adibox-cache-bundle
   

   Enable the bundle in config/app.php under providers:

   Adibox\CacheBundle\AdiboxCacheBundle::class,
   

2. Basic Configuration Publish the default config (optional):

   php artisan adibox:cache:publish
   

   Configure cache drivers in config/cache.php (ensure your default driver is supported).

3. First Use Case: Caching a Complex Render Use the CacheRenderer service to cache a complex data structure (e.g., a multi-step query or API response):

   use Adibox\CacheBundle\Renderer\CacheRenderer;
   
   class MyController extends Controller
   {
       public function __construct(private CacheRenderer $cacheRenderer) {}
   
       public function complexData()
       {
           $key = 'complex_data_key';
           $data = $this->cacheRenderer->render($key, function () {
               return $this->fetchComplexData(); // Your expensive operation
           }, 3600); // Cache for 1 hour
   
           return response()->json($data);
       }
   }
   

Implementation Patterns

Workflows

1. Conditional Caching Use tags or dependencies to invalidate cache dynamically:

   $this->cacheRenderer->render('user_profile_123', fn() => $userProfile, 3600, ['user:123']);
   

   Later, invalidate by tag:

   $this->cacheRenderer->invalidateTag('user:123');
   

2. Fallback Logic Combine with Laravel’s Cache::remember for fallback behavior:

   $data = $this->cacheRenderer->render('fallback_data', function () {
       return Cache::remember('fallback_key', 300, function () {
           return $this->fetchFallbackData();
       });
   });
   

3. Cache Warming Pre-load critical data during maintenance mode or cron jobs:

   $this->cacheRenderer->render('homepage_hero', fn() => $heroData, 86400, [], true); // Force refresh
   

Integration Tips

• Laravel Echo/Pusher: Cache WebSocket events or presence data:

  $this->cacheRenderer->render('pusher_events', fn() => $this->getEvents(), 60);
  

• API Responses: Cache paginated or filtered API results:

  $this->cacheRenderer->render('api_users_active', fn() => $this->getActiveUsers(), 1800, [], true);
  

• Blade Views: Cache partials or full views (if supported):

  $this->cacheRenderer->render('dashboard_stats', fn() => view('partials.stats')->render(), 900);
  

Gotchas and Tips

Pitfalls

1. Serialization Issues

   • The bundle may struggle with non-serializable objects (e.g., closures, resources). Use json_encode/json_decode wrappers:

     $this->cacheRenderer->render('data', fn() => ['value' => json_encode($nonSerializableObject)], 3600);
     

   • Fix: Implement __serialize()/__unserialize() or use igbinary cache driver.

2. Tag Invalidation Race Conditions

   • If multiple processes invalidate the same tag simultaneously, stale data may briefly appear.
   • Fix: Use Cache::tags() for atomic invalidation or implement a lock:

     Cache::lock('tag_invalidation_lock', 5, function () {
         Cache::tags(['user:123'])->flush();
     });
     

3. Memory Leaks

   • Large cached objects (e.g., entire databases) can bloat memory.
   • Fix: Set aggressive TTLs (e.g., 300s) or use Cache::forget() for critical paths.

Debugging

• Cache Miss/Hit Logging Enable debug mode in config/adibox_cache.php:

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

  Logs will appear in storage/logs/adibox_cache.log.

• Inspect Cached Keys Use Artisan to list all cached keys:

  php artisan adibox:cache:list
  

Extension Points

1. Custom Cache Drivers Extend Adibox\CacheBundle\Driver\AbstractDriver to support Redis clusters or custom storage:

   class CustomDriver extends AbstractDriver
   {
       public function get($key) { /* ... */ }
       public function set($key, $value, $ttl) { /* ... */ }
   }
   

   Register in config/adibox_cache.php:

   'drivers' => [
       'custom' => \App\Cache\CustomDriver::class,
   ],
   

2. Event Listeners Hook into cache events (e.g., CacheMissed, CacheHit) via:

   Cache::addListener(function ($event) {
       if ($event instanceof CacheMissed) {
           Log::info("Cache missed for: {$event->getKey()}");
       }
   });
   

3. Cache Compression Enable GZIP compression for large payloads in the driver:

   $compressed = gzcompress(serialize($data));
   Cache::put($key, $compressed, $ttl);