Stash Laravel Package

Getting Started

Begin by installing Stash via Composer (composer require tedivm/stash). The library follows PSR-6, so start with the Pool class and a driver like FileSystem for local development:

use Stash\Pool;
use Stash\Driver\FileSystem;

$pool = new Pool(new FileSystem(['path' => __DIR__ . '/cache']));
$item = $pool->getItem('my_key');
$item->set('Hello, cache!');
$item->expiresAfter(3600); // 1 hour
$pool->save($item);

// Later...
if ($cached = $pool->getItem('my_key')->get()) {
    echo $cached; // "Hello, cache!"
}

The official docs at stashphp.com provide deeper examples—start with the "Quick Start" and "Keys" sections to grasp key hierarchy and cache invalidation patterns.

Implementation Patterns

• Multi-tier caching with Composite Driver: Combine fast in-memory (e.g., Redis) with durable filesystem storage:

  $redisDriver = new Stash\Driver\Redis(['servers' => [['host' => '127.0.0.1', 'port' => 6379]]]);
  $fsDriver = new Stash\Driver\FileSystem(['path' => '/var/cache/stash']);
  $composite = new Stash\Driver\Composite([$redisDriver, $fsDriver]);
  $pool = new Pool($composite);
  

• Nested keys for bulk invalidation: Use slashes to group related data (e.g., 'users/profiles/123'), then call $pool->invalidate('users/profiles') to clear all user profiles at once.
• Session storage: Register Stash as a PHP session handler for scalable session management:

  use Stash\Driver\Redis;
  use Stash\Pool;
  use Stash\Driver\Session;
  
  $pool = new Pool(new Redis([...]));
  Session::registerHandler($pool);
  

• Long-running tasks: Use Item::extend($ttl) to keep volatile caches alive during extended operations (e.g., API responses during heavy processing).

Gotchas and Tips

• Filesystem quirks on Windows: Ensure path lengths don’t exceed Windows’ 260-char limit; use FileSystem’s path config and avoid deeply nested keys. Changelog notes fixes for this (e.g., v0.11.5).
• Redis username auth: For Redis clusters with auth, v0.17.4+ supports 'username' => '...' in driver options—don’t overlook this for managed services (e.g., AWS ElastiCache).
• Type safety in PHP 8.4+: Stash v1.1.0+ uses explicit nullable types—no deprecation warnings for ?DateTime or ?int returns like Item::getExpiration().
• Invalidate vs. clear: invalidate() removes items from all drivers (Composite-aware), while clear() only flushes the current driver. Prefer invalidate() for multi-tier setups.
• Logging integration: Inject a PSR-3 logger early via $pool->setLogger($logger) to debug cache misses and track hit rates. Logging propagates to all Item instances derived from the pool.
• Ephemeral driver pitfalls: Data resets per request—use only for unit tests or CLI tools. For persistence, always default to FileSystem or Redis in production.