repository·3.x·Indexed 19 days ago
https://github.com/friendsofsymfony/foshttpcachebundleA Symfony bundle providing advanced HTTP caching management. It enables sophisticated header configuration via path, host, or controller rules and supports active cache invalidation (purge, refresh, and tag-based) for proxies like Varnish, Nginx, and Symfony's built-in HttpCache. Key features include a Flash Message Listener to prevent session-based cache pollution and a CacheManager for manual or automatic invalidation.
The bundle provides several ways to manage cache behavior through attributes, configuration, or manual calls:
| Functionality | Attributes | Configuration | Manually |
|---|---|---|---|
| Set Cache-Control headers | Symfony cache attributes | Symfony cache control | |
| Tag and invalidate | #[Tag] | rules | cache manager |
| Invalidate routes | invalidators | cache manager | |
| Invalidate paths | invalidators | cache manager |
When defining rules under cache_control, you can use the match key to target specific requests. Supported matching criteria include:
^login.example.com$).attributes: { _controller: ^AcmeBundle:Default:.* }).query_string: (^|&)token=).path: ^/$).fos_http_cache:
cache_control:
rules:
# Match by host
- match:
host: ^login.example.com$
headers:
cache_control: { public: false }
# Match by controller
- match:
attributes: { _controller: ^AcmeBundle:Default:.* }
headers:
cache_control: { public: true }
# Match by query parameter
- match:
query_string: (^|&)token=
headers:
cache_control: { public: false }
# Match by path
- match:
path: ^/
headers:
cache_control: { public: true }User Context allows you to cache content that varies based on user groups (e.g., guest, editor, admin) without storing a separate cache for every individual user. It uses a 'preflight' request mechanism to determine a unique hash for the user's context.
The Workflow:
/foo).UserContextListener intercepts it after the Symfony firewall is applied, calculates a hash via a HashGenerator, and returns a response containing the hash in a custom header (default: X-User-Context-Hash)./foo as a header, and restarts the request.Vary: X-User-Context-Hash. The proxy then caches the response specifically for that hash.This feature is compatible with Varnish and symfony-http-cache.
By default, FOSHttpCacheBundle follows RFC 7231, treating responses with the following status codes as cacheable:
200, 203, 204, 206, 300, 301, 404, 405, 410, 414, or 501.
You can customize this behavior by configuring the cacheable.response section in your bundle configuration.
The match section is used within cache <headers>, invalidation <invalidation>, and tag rule <tags> configurations to restrict rules to specific requests and responses.
A match section contains one or more criteria, all of which are treated as regular expressions. For a rule to apply, the request must satisfy all provided criteria.
Important Note on Encoding: Some parts of the URL are URL-encoded. However, the expressions provided in this configuration MUST NOT be URL-encoded. The matcher automatically handles encoding before performing the match.
match:
host: ^login.example.com$
path: ^/$
query_string: (^|&)token=By default, Symfony flash messages are stored in the user session. When using features like user context to cache pages for logged-in users, including flash messages in the rendered HTML can cause notifications to be mixed up between different users or cached incorrectly.
To solve this, the Flash Message Listener moves flash messages from the session into a cookie. The response is sent with a SET-COOKIE header, which ensures the response is not cached.
Workflow:
SET-COOKIE header.Prerequisites: None.
In the context of FOSHttpCacheBundle, a request is considered safe if it uses one of the following HTTP methods:
GETHEADThe cache_control configuration uses a list of rules to manage HTTP response headers. Each rule consists of a match section and a headers section.
match section, the corresponding headers are applied to the response.defaults.overwrite setting.headers.overwrite: true option.If overwrite is true, the headers defined in that rule will replace existing headers.
fos_http_cache:
cache_control:
defaults:
overwrite: false
rules:
- match:
host: ^login.example.com$
headers:
overwrite: true
cache_control:
public: false
max_age: 0
s_maxage: 0While the bundle is fully functional with Varnish and used in production environments, other proxies have limited support:
The FOS\HttpCacheBundle\CacheManager is used to explicitly invalidate or refresh content in your caching proxy.
The CacheManager is available in the Symfony DI container via autowiring.
use FOS\HttpCacheBundle\CacheManager;
// Injected via autowiring
public function __construct(CacheManager $cacheManager) { ... }The bundle provides several capabilities for managing HTTP cache: