Merge pull request #517 from FriendsOfSymfony/improve-xkey-bundle-doc

clarify how to use xkey

Author: dbu

Resources/doc/features/tagging.rst

@@ -18,6 +18,12 @@ version of `Linked Cache Invalidation`_ (LCI), allows you to:
 * :ref:`invalidate the responses by tag <foshttpcache:tags>` (e.g., invalidate
  all responses that are tagged ``article-42``)
 
+.. hint::
+
+ When working with Varnish, it is recommended to use the xkey vmod for
+ efficient invalidation. See :ref:`Tagging with Varnish <foshttpcache:varnish_tagging>`
+ and :ref:`configure the proxy client for purgekeys <config_varnish_tag_mode>`.
+
 Basic Configuration
 -------------------
 

Resources/doc/reference/configuration/proxy-client.rst

@@ -92,12 +92,15 @@ URL may contain a path. If you access your web application on a port other than
  Double-check ``base_url``, for if it is mistyped, no content will be
  invalidated.
 
+.. _config_varnish_tag_mode:
+
 ``tag_mode``
 """"""""""""
 
 **type**: ``string`` **options**: ``ban``, ``purgekeys`` **default**: ``ban``
 
-Select whether to invalidate tags using the `xkey vmod`_ or with BAN requests.
+Select whether to invalidate tags using the :ref:`xkey vmod <foshttpcache:varnish_tagging>`
+or with BAN requests.
 
 Xkey is an efficient way to invalidate Varnish cache entries based on
 :doc:`tagging </features/tagging>`.
@@ -110,10 +113,13 @@ default ``xkey-softpurge``.
 
 .. note::
 
- To use the purgekeys method, you need the `xkey vmod`_ enabled and VCL to
+ To use the purgekeys method, you need the xkey vmod enabled and VCL to
  handle xkey invalidation requests as explained in the
  :ref:`FOSHttpCache library docs on xkey support <foshttpcache:varnish_tagging>`.
 
+ ``tags.response_header`` will automatically default to ``xkey`` when you
+ set the mode to purgekeys.
+
 ``tags_header``
 """""""""""""""
 

Resources/doc/reference/configuration/tags.rst

@@ -33,9 +33,16 @@ incompatible proxies:
 ``response_header``
 -------------------
 
-**type**: ``string`` **default**: ``X-Cache-Tags``
+**type**: ``string`` **default**: ``X-Cache-Tags`` resp. ``xkey``
 
-Custom HTTP header that tags are stored in.
+HTTP header that tags are stored in.
+
+.. note::
+
+ If you use :ref:`Varnish xkey system <config_varnish_tag_mode>`, (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.
 
 .. include:: /includes/expression-language.rst