Merge pull request #354 from FriendsOfSymfony/rework-response-tagger

Rework response tagger

Author: dbu

CHANGELOG.md

@@ -40,6 +40,8 @@ See also the [GitHub releases page](https://github.com/FriendsOfSymfony/FOSHttpC
 * Abstracting tags by adding new `TagCapable` for ProxyClients.
 * Added `strict` option to `ResponseTagger` that throws an exception when empty
   tags are added. By default, empty tags are ignored.
+* Added `TagHeaderFormatter` interface that is used within the `ResponseTagger`
+  to provide the header name and for formatting the tags header value.
 
 ### Varnish
 
@@ -77,6 +79,14 @@ See also the [GitHub releases page](https://github.com/FriendsOfSymfony/FOSHttpC
   `ProxyTestCase`; use the traits `CacheAssertions` and `HttpCaller` instead.
 * Added HTTP method parameter to `HttpCaller::getResponse()`.
 
+2.0.0-beta3
+-----------
+
+* **BC break:** The `ResponseTagger` no longer expects an instance of
+  `TagCapable` as first argument. To adjust the tag header name or the way the
+  tags are formatted, use the new `header_formatter` option with a
+  `TagHeaderFormatter`.
+
 1.4.2
 -----
 

doc/proxy-clients.rst

@@ -94,13 +94,14 @@ dispatcher as explained above and pass it to the Varnish client::
 
 You can also pass some options to the Varnish client:
 
-* ``tags_header`` (X-Cache-Tags): Allows you to change the HTTP header used for
-  tagging. If you change this, make sure to use the correct header name in your
-  :doc:`proxy server configuration <proxy-configuration>`;
-* ``header_length`` (7500): Control the maximum header size when invalidating
+* ``tags_header`` (default: ``X-Cache-Tags``): The HTTP header used to specify
+  which tags to invalidate when sending invalidation requests to the caching
+  proxy. Make sure that your :ref:`Varnish configuration <varnish_tagging>`
+  corresponds to the header used here;
+* ``header_length`` (default: 7500): Control the maximum header size when invalidating
   tags. If there are more tags to invalidate than fit into the header, the
   invalidation request is split into several requests;
-* ``default_ban_headers`` Map of headers that are set on each ban request,
+* ``default_ban_headers`` (default: []): Map of headers that are set on each ban request,
   merged with the built-in headers.
 
 Additionally, you can specify the request factory used to build the

doc/response-tagging.rst

@@ -1,8 +1,8 @@
 Response Tagging
 ================
 
-The ``ResponseTagger`` helps you keep track tags for a response, which can be
-added to response headers that you can later use to invalidate all cache
+The ``ResponseTagger`` helps you keep track of tags for a response. It can add
+the tags as a response header that you can later use to invalidate all cache
 entries with that tag.
 
 .. _tags:
@@ -12,23 +12,40 @@ Setup
 
 .. note::
 
-    Make sure to :doc:`configure your proxy <proxy-configuration>` for tagging first.
+    Make sure to :doc:`configure your proxy <proxy-configuration>` for tagging
+    first.
 
-The response tagger is a decorator around a proxy client that implements
-the ``TagCapable`` interface, handling adding tags to responses::
+The response tagger uses an instance of ``TagHeaderFormatter`` to know the
+header name used to mark tags on the content and to format the tags into the
+correct header value. This library ships with a
+``CommaSeparatedTagHeaderFormatter`` that formats an array of tags into a
+comma-separated list. This format is expected for invalidation with the
+Varnish reverse proxy. When using the default settings, everything is created
+automatically and the ``X-Cache-Tags`` header will be used::
 
     use FOS\HttpCache\ResponseTagger;
 
-    // $proxyClient already created, implementing FOS\HttpCache\ProxyClient\Invalidation\TagCapable
-    $responseTagger = new ResponseTagger($proxyClient);
+    $responseTagger = new ResponseTagger();
 
 .. _response_tagger_optional_parameters:
 
+If you need a different behavior, you can provide your own implementation of
+the ``TagHeaderFormatter`` interface. But be aware that your
+:ref:`Varnish configuration <varnish_tagging>` has to match with the tag on the response.
+For example, to use a different header name::
+
+    use FOS\HttpCache\ResponseTagger;
+    use FOS\HttpCache\TagHeaderFormatter;
+
+    $formatter = new CommaSeparatedTagHeaderFormatter('Custom-Header-Name');
+    $responseTagger = new ResponseTagger(['header_formatter' => $formatter]);
+
 The response tagger validates tags that you set. By default, it simply ignores
-empty strings. You can set the response tagger to strict mode to have it throw
-an ``InvalidTagException`` on empty tags::
+empty strings and does not add them to the list of tags. You can set the
+response tagger to strict mode to have it throw an ``InvalidTagException`` on
+empty tags::
 
-    $responseTagger = new ResponseTagger($proxyClient, ['strict' => true]);
+    $responseTagger = new ResponseTagger(['strict' => true]);
 
 Usage
 ~~~~~

doc/varnish-configuration.rst

@@ -175,26 +175,34 @@ Tagging
 Feature: :ref:`cache tagging <tags>`
 
 If you have included ``fos_ban.vcl``, tagging will be automatically enabled
-using an ``X-Cache-Tags`` header.
+with the ``X-Cache-Tags`` header for both marking the tags on the response and
+for the invalidation request to tell what tags to invalidate.
 
-If you need to use a different tag for the headers than the default
-``X-Cache-Tags`` used in ``fos_ban.vcl``, you will have to write your own VCL
-code for tag invalidation and change the tagging header
-:ref:`configured in the cache invalidator <varnish_custom_tags_header>`. Your custom
-VCL will look like this:
+If you use a different name for :doc:`response tagging <response-tagging>` than
+the default ``X-Cache-Tags`` or a different name for specifying which tags to
+invalidate in your :ref:`cache invalidator configuration <varnish_custom_tags_header>`
+you have to write your own VCL code for tag invalidation. Your custom VCL will
+look like this:
 
 .. configuration-block::
 
     .. literalinclude:: ../resources/config/varnish/fos_ban.vcl
         :language: varnish
-        :emphasize-lines: 17-22,49-50
+        :emphasize-lines: 17-23,50-51
         :linenos:
 
     .. literalinclude:: ../resources/config/varnish-3/fos_ban.vcl
         :language: varnish3
-        :emphasize-lines: 17-22,49-50
+        :emphasize-lines: 17-23,50-51
         :linenos:
 
+.. hint::
+
+    The line you need to adjust from the code above is line 21. The left side
+    is the header used to tag the response, the right side is the header used
+    when sending invalidation requests. If you change one or the other header
+    name, make sure to adjust the configuration accordingly.
+
 .. _varnish user context:
 
 User Context

resources/config/varnish-3/fos_ban.vcl

@@ -18,6 +18,7 @@ sub fos_ban_recv {
             ban("obj.http.X-Host ~ " + req.http.X-Host
                 + " && obj.http.X-Url ~ " + req.http.X-Url
                 + " && obj.http.content-type ~ " + req.http.X-Content-Type
+                // the left side is the response header, the right side the invalidation header
                 + " && obj.http.X-Cache-Tags ~ " + req.http.X-Cache-Tags
             );
         } else {

resources/config/varnish/fos_ban.vcl

@@ -18,6 +18,7 @@ sub fos_ban_recv {
             ban("obj.http.X-Host ~ " + req.http.X-Host
                 + " && obj.http.X-Url ~ " + req.http.X-Url
                 + " && obj.http.content-type ~ " + req.http.X-Content-Type
+                // the left side is the response header, the right side the invalidation header
                 + " && obj.http.X-Cache-Tags ~ " + req.http.X-Cache-Tags
             );
         } else {

src/ProxyClient/Invalidation/TagCapable.php

@@ -30,23 +30,4 @@ interface TagCapable extends ProxyClient
      * @return $this
      */
     public function invalidateTags(array $tags);
-
-    /**
-     * Get value for the tags header as it should be included in the response.
-     *
-     * This does all necessary escaping and concatenates the tags in a way that
-     * individual tags can be invalidated by this client.
-     *
-     * @param array $tags
-     *
-     * @return string
-     */
-    public function getTagsHeaderValue(array $tags);
-
-    /**
-     * Get the HTTP header name for the cache tags.
-     *
-     * @return string
-     */
-    public function getTagsHeaderName();
 }

src/ProxyClient/MultiplexerClient.php

@@ -98,22 +98,6 @@ public function flush()
         return $count;
     }
 
-    /**
-     * {@inheritdoc}
-     */
-    public function getTagsHeaderValue(array $tags)
-    {
-        return $this->invokeFirst(TagCapable::class, 'getTagsHeaderValue', [$tags]);
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getTagsHeaderName()
-    {
-        return $this->invokeFirst(TagCapable::class, 'getTagsHeaderName', []);
-    }
-
     /**
      * Forwards tag invalidation request to all clients.
      *

src/ProxyClient/Noop.php

@@ -48,22 +48,6 @@ public function invalidateTags(array $tags)
         return $this;
     }
 
-    /**
-     * {@inheritdoc}
-     */
-    public function getTagsHeaderValue(array $tags)
-    {
-        return '';
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getTagsHeaderName()
-    {
-        return 'X-Noop-Cache-Tags';
-    }
-
     /**
      * {@inheritdoc}
      */

src/ProxyClient/Varnish.php

@@ -36,6 +36,15 @@ class Varnish extends HttpProxyClient implements BanCapable, PurgeCapable, Refre
     const HTTP_HEADER_HOST = 'X-Host';
     const HTTP_HEADER_URL = 'X-Url';
     const HTTP_HEADER_CONTENT_TYPE = 'X-Content-Type';
+
+    /**
+     * Default name of the header used to invalidate content with specific tags.
+     *
+     * This happens to be the same as TagHeaderFormatter::DEFAULT_HEADER_NAME
+     * but does not technically need to be the same.
+     *
+     * @var string
+     */
     const DEFAULT_HTTP_HEADER_CACHE_TAGS = 'X-Cache-Tags';
 
     /**
@@ -64,22 +73,6 @@ public function invalidateTags(array $tags)
         return $this;
     }
 
-    /**
-     * {@inheritdoc}
-     */
-    public function getTagsHeaderValue(array $tags)
-    {
-        return implode(',', array_unique($this->escapeTags($tags)));
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getTagsHeaderName()
-    {
-        return $this->options['tags_header'];
-    }
-
     /**
      * {@inheritdoc}
      */