Weave Code
Cache Contracts Laravel Package
symfony/cache-contracts
A set of cache abstractions extracted from Symfony components. It defines interfaces such as CacheInterface, CacheItemInterface, and TagAwareCacheInterface, letting libraries depend on proven cache semantics without binding to a concrete implementation.
Generic abstractions related to caching
Frequently asked questions about Cache Contracts
- What is symfony/cache-contracts used for in a Laravel application?
- It is an interfaces-only package that defines the cache abstractions Symfony and Laravel already share: CacheInterface, CacheItemPoolInterface, CacheItemInterface and TagAwareCacheInterface. It lets your code and third-party libraries depend on proven cache semantics instead of a concrete backend such as Redis or the array driver. In Laravel terms it is the seam between your caching policy and whatever store config/cache.php points at. It ships no implementation, so it never caches anything on its own.
- Do I need to install symfony/cache-contracts separately in Laravel?
- Usually no. Any modern Laravel app already has it transitively, because illuminate/cache is built on symfony/cache, which depends on these contracts. Adding an explicit composer require only matters if your own package or a library type-hints the interfaces and you want to declare that dependency directly. Check composer.lock or run composer why symfony/cache-contracts before changing anything.
- Which versions of symfony/cache-contracts work with Laravel and PHP?
- Contract majors track Symfony majors, so v2 lines up with the symfony/cache v5 era and v3 with later majors, each with its own minimum PHP version. In practice your Laravel version pins the allowed contracts major through Composer constraints, so the real answer lives in your composer.lock rather than the README. If a third-party package demands a different major, you get a resolution conflict, which is the most likely failure mode here.
- Does symfony/cache-contracts actually store or retrieve cached data?
- No. The package ships interfaces only, so nothing is cached until you pair it with an implementation such as a symfony/cache adapter or your own class implementing CacheItemPoolInterface. That means the real unit of delivery is always adopting or writing a driver, not installing the contracts. Teams that treat the contracts as a caching feature usually stall right after the composer require.
- How do I inject CacheInterface or CacheItemPoolInterface into a Laravel service?
- Bind the interface to a concrete adapter in a service provider, then type-hint the interface in your constructor so tests can swap in a fake or an ArrayAdapter. Application code that calls Cache::get, Cache::put or Cache::remember through the facade stays untouched, which is what keeps adoption non-invasive. Type-hinting the interface instead of a concrete adapter is what makes the array driver viable in unit tests.
- What is the difference between CacheInterface and CacheItemPoolInterface in these contracts?
- CacheInterface is a slim get, set and delete style API, while CacheItemPoolInterface is the full PSR-6 item-pool flow of getItem, set and save. PSR-6 gives you fine-grained control and interoperability but adds ceremony that is often overkill next to Laravel's Cache::remember. Choose deliberately, because many projects only need the simpler surface and end up paying complexity costs for a pool they never use.
- Why does tag-based invalidation not work with my cache adapter?
- TagAwareCacheInterface is only honoured by adapters that genuinely support tagging, such as symfony/cache's TagAwareAdapter. ArrayAdapter is per-request only, and FilesystemAdapter serialises non-scalars and has its own tag behaviour, so code assuming uniform semantics across adapters breaks in production. Verify tag support per environment instead of trusting the interface alone.
- How do I write a custom cache driver that implements symfony/cache-contracts?
- Implement CacheItemPoolInterface, plus CacheItemInterface for your item objects, then register the driver so Laravel's cache manager can resolve it, typically via Cache::extend or a custom store entry in config/cache.php. Keep TTL, serialisation and tag handling consistent with the stock adapters so application code behaves the same after a switch. Plan a rollback path where traffic can revert to a stock Laravel driver through configuration alone.
- Can symfony/cache-contracts cause Composer conflicts when upgrading Laravel?
- Yes, version skew is the realistic risk. Laravel's constraints pin a contracts major, and a third-party package requiring a different major either blocks the upgrade or forces a resolution conflict. Before upgrading, run composer why symfony/cache-contracts to see which packages constrain the major, then decide who owns the alignment policy between Laravel, symfony/cache and the contracts.
- What are the alternatives to symfony/cache-contracts for cache abstraction in PHP?
- The baseline alternatives are psr/cache for PSR-6 and psr/simple-cache for PSR-16, plus Laravel's own Illuminate\Contracts\Cache\Repository when you only care about Laravel. Symfony's contracts add CacheInterface and TagAwareCacheInterface on top of PSR-6, which is why so many libraries type-hint them. PSR-16 is a different package concern reached through SimpleCacheAdapter, so conflating PSR-6 and PSR-16 is a common and costly scoping error.
Weaver
How can I help you explore Laravel packages today?