tags

Create tag rules in your application configuration to set tags on responses and invalidate them. See the tagging feature chapter for an introduction. Also have a look at configuring the proxy client for cache tagging.

enabled

type: enum, default: auto, options: true, false, auto

Enabled by default if you have configured the cache manager with a proxy client.

Note

If you use a proxy client that does not support tag invalidation, cache tagging is not possible.

If you leave enabled on auto, tagging will only be activated when using the Varnish or Symfony proxy client.

When using the noop proxy client or a custom service, auto will also lead to tagging being disabled. If you want to use tagging in one of those cases, you need to explicitly enable tagging.

Enables tag annotations and rules. If you want to use tagging, it is recommended that you set this to true so you are notified of missing dependencies and incompatible proxies:

# app/config/config.yml
fos_http_cache:
    tags:
        enabled: true

response_header

type: string default: X-Cache-Tags resp. xkey

HTTP header that tags are stored in.

Note

If you use Varnish xkey system, (having proxy_client.varnish.tag_mode: purgekeys), the response header defaults to xkey rather than X-Cache-Tags. Do not change the header in that case, the xkey header name is hardcoded into the xkey vmod.

expression_language

type: string

If your application is using a custom expression language which is extended from Symfony’s expression language component, you need to define it as a service and configure it as expression_language in the sections where you want to use it.

Your custom expression functions can then be used in both the tag_expressions section of the tag configuration and @tag annotations.

# app/config/config.yml
fos_http_cache:
    tags:
        expression_language: app.expression_language

max_header_value_length

type: integer default: null

By default, the generated response header will not be split into multiple headers. This means that depending on the amount of tags generated in your application the value of that header might become pretty long. This again might cause issues with your web server, as it usually has a default maximum header length and will reject the request if the header exceeds this value. Using this configuration key, you can configure a maximum length in bytes which will split your value into multiple headers. Note that you might have to update your proxy configuration because it needs to be able to handle multiple headers instead of just one.

# app/config/config.yml
fos_http_cache:
    tags:
        max_header_value_length: 4096

Note

4096 bytes is generally a good choice because it seems like most web servers have a maximum value of 4 KB configured.

strict

type: boolean default: false

Set this to true to throw an exception when an empty or null tag is added.

# app/config/config.yml
fos_http_cache:
    tags:
        strict: true

rules

type: array

Write your tagging rules by combining a match definition with a tags array. Rules are checked in the order specified, where the first match wins. These tags will be set on the response when all of the following are true:

  1. the HTTP request matches all criteria defined under match

  2. the HTTP request is safe (GET or HEAD)

  3. the HTTP response is considered cacheable

When the definition matches an unsafe request (so 2 is false), the tags will be invalidated instead.

match

type: array

A match definition that when met, will execute the rule effect. See match.

tags

type: array

Tags that should be set on responses to safe requests; or invalidated for unsafe requests.

# app/config/config.yml
fos_http_cache:
    tags:
        rules:
            -
                match:
                    path: ^/news
                tags: [news-section]

tag_expressions

type: array

You can dynamically refer to request attributes using expressions. Assume a route /articles/{id}. A request to path /articles/123 will set/invalidate tag articles-123 with the following configuration:

# app/config/config.yml
fos_http_cache:
    tags:
        rules:
            -
                match:
                    path: ^/articles
                tags: [articles]
                tag_expressions: ["'article-'~id"]

The expression has access to all request attributes and the request itself under the name request.

You can combine tags and tag_expression in one rule.