Cache Contracts Laravel Package

Getting Started

Start by installing via Composer: composer require symfony/cache-contracts. This package provides only interfaces (TagAwareCacheInterface, CacheInterface, ItemInterface, etc.)—no concrete implementations—so you must combine it with a driver (e.g., symfony/cache for PSR-6/PSR-16 adapters like Redis, ArrayAdapter, or Doctrine Cache). The canonical first use is caching simple values: inject Psr\Cache\CacheItemPoolInterface (via symfony/cache's Adapter\AdapterInterface or FilesystemAdapter) and use getItem() → set() → save(). Refer to Symfony’s Cache component docs for concrete examples—this package is the abstraction layer they rely on.

Implementation Patterns

• Dependency Injection: Inject CacheItemPoolInterface (PSR-6) or CacheInterface (Symfony-style, PSR-6 subset) into services, not concrete adapters—enables testing with ArrayAdapter.
• Tag-based invalidation: Use TagAwareAdapter (from symfony/cache) to clear multiple cached items by tag, e.g., invalidateTags(['products']) after updating product data.
• Fallback chain: Wrap adapters (e.g., CachePoolDecorator with ArrayAdapter → RedisAdapter) for graceful degradation: in-memory first, then persistent.
• Deferred commits: Batch operations with defer() and commit() for performance when storing many items.
• Integration with Laravel: Use Cache::driver() under the hood—Laravel’s cache is built on Symfony’s adapters (which depend on this contracts package).

Gotchas and Tips

• No implementation here: Confusingly, symfony/cache-contracts alone won’t cache anything. You must pair it with symfony/cache or a PSR-6-compatible library (e.g., doctrine/cache with bridge).
• Versioning pitfalls: The package version (e.g., v2.0 vs v3.0) aligns with Symfony’s major versions and PSR-6/PSR-16 adoption—ensure your adapter matches the contract version. symfony/cache v5+ uses cache-contracts v2+.
• Serialization quirks: Adapter-specific behavior affects serialized storage (e.g., FilesystemAdapter serializes non-scalar values; ArrayAdapter does not persist across requests).
• Debugging stale cache: Run cache:clear in Symfony but note: ArrayAdapter lives only in memory—ideal for tests but useless in HTTP requests.
• Extension point: Implement custom adapters by extending CacheItemPoolDecorator and overriding doFetch(), doSave(), etc., or implement CacheInterface directly if full PSR-6 compliance isn’t needed.
• PSR-16 (SimpleCache) is separate: This package implements PSR-6; for PSR-16, use psr/cache and symfony/cache’s SimpleCacheAdapter. Don’t conflate the two.