cache / cache-bundle
Symfony integration for PSR-6 cache pools
Maintainers
Requires
- php: ^8.2
- cache/prefixed-cache: ^2.0
- cache/session-handler: ^2.0
- cache/tag-interop: ^2.0
- cache/taggable-cache: ^2.0 || ^3.0
- psr/cache: ^3.0
- psr/container: ^2.0
- symfony/config: ^6.4 || ^7.0 || ^8.0
- symfony/console: ^6.4 || ^7.0 || ^8.0
- symfony/dependency-injection: ^6.4 || ^7.0 || ^8.0
- symfony/framework-bundle: ^6.4 || ^7.0 || ^8.0
- symfony/http-foundation: ^6.4 || ^7.0 || ^8.0
- symfony/http-kernel: ^6.4 || ^7.0 || ^8.0
- symfony/lock: ^6.4 || ^7.0 || ^8.0
- symfony/routing: ^6.4 || ^7.0 || ^8.0
- symfony/var-dumper: ^6.4 || ^7.0 || ^8.0
Requires (Dev)
- cache/array-adapter: ^3.0
- cache/cache: ^2.0 || ^3.0
- mockery/mockery: ^1.6
- nyholm/symfony-bundle-test: ^3.1
- php-cs-fixer/shim: 3.95.19
- phpstan/phpstan: 2.2.8
- phpunit/phpunit: ^11.5
- symfony/web-profiler-bundle: ^6.4 || ^7.0 || ^8.0
- symfony/yaml: ^6.4 || ^7.0 || ^8.0
- twig/twig: ^3.12
Suggests
- cache/adapter-bundle: Registers PSR-6 cache implementations as Symfony services
README
This Symfony bundle connects PSR-6 cache pools to framework services. It supports session storage, route caching, PSR-3 logging, the Symfony profiler, and targeted cache clearing. Use Adapter Bundle when you also need to register cache pool services from configuration.
Version 2.2 requires PHP 8.2 or newer, Symfony 6.4, 7, or 8, and PSR Cache 3. It supports PHP Cache 2 and 3 aggregate releases.
Installation
composer require cache/cache-bundle:^2.2
Symfony Flex may register the bundle automatically. Otherwise, add it to config/bundles.php:
<?php return [ Cache\CacheBundle\CacheBundle::class => ['all' => true], ];
Configuration
The referenced cache pool must already be registered as a service:
# config/packages/cache.yaml cache: session: enabled: true service_id: cache.provider.app ttl: 7200 lock_factory: lock.factory lock_ttl: 300 router: enabled: true service_id: cache.provider.app ttl: 86400 logging: enabled: true logger: monolog.logger.cache data_collector: enabled: true include_values: false
Enable Symfony sessions when using the session integration:
# config/packages/framework.yaml framework: session: true
The session handler acquires an exclusive Symfony lock before reading a session and holds it until the session closes or is destroyed. lock_ttl is the maximum expected request duration in seconds. Increase it when a request can keep a session open for longer than five minutes.
Symfony uses a local semaphore or file lock by default. That is sufficient for one application host. When several hosts share the session cache, configure framework.lock with a shared store such as Redis so every host contends for the same lock. Set lock_factory when the session handler should use a named or custom Symfony lock factory.
The profiler collector is enabled by default in debug mode. Set cache.data_collector.enabled explicitly to override that default.
Set cache.data_collector.include_values to false when cached values are large or sensitive. The collector omits call arguments and results from profiler storage and the panel. It still records operations, timings, hit ratios, and per-pool statistics.
Profiler decoration preserves native tag support. Chain providers keep member-level calls, so the panel shows each member's hits and misses. The collector records failed operations and tag invalidations. It also clears its call buffer between requests in long-running workers.
Clear a configured pool with bin/console cache:flush:
bin/console cache:flush session bin/console cache:flush router bin/console cache:flush symfony bin/console cache:flush provider cache.provider.app bin/console cache:flush all
Using version 3 packages
CacheBundle 2.2 supports PHP Cache 3 while it remains compatible with PHP Cache 2.
PHP Cache 3 stores a generation snapshot with each tagged item. Each tag also has a generation marker. Version 2 workers cannot safely read or update this storage format.
Stop or drain all workers, clear each shared cache, and then deploy CacheBundle 2.2 with PHP Cache 3. Use the same sequence before a rollback.
Upgrading from 1.x
Version 2 removes the Doctrine, annotation, serializer, and validation integrations. Configure those consumers with their native Symfony or Doctrine cache options instead. The generated subclass profiler proxies are also replaced by a regular PSR-6 decorator.
Session storage now requires Symfony Lock and serializes access to each session ID. Review lock_ttl and use a shared lock store before deploying to more than one application host.
PHP Cache 2 changes APCu payloads, Redis and Predis tag indexes, namespaced tag indexes, and hierarchy storage paths. Do not mix version 1 and version 2 workers on an affected store.
Clear a namespaced store when a namespace contains bytes outside [A-Za-z0-9_.] or lowercase _x. Also clear it when a public key contains |, !, or lowercase _x.
Clear namespaced stores containing tagged or hierarchy items. Clear a prefixed store when its prefix contains bytes outside [A-Za-z0-9_.] or lowercase _x.
Stop or drain old workers, clear each affected store, and then deploy version 2. Follow the same sequence before rolling back.
See the full Cache Bundle documentation for all options.
Contributing
Send pull requests to the GitHub repository. Report problems on the GitHub issue tracker.