cleanup documentation for tag formatter

Author: dbu

CHANGELOG.md

@@ -40,8 +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 a `TagHeaderFormatter` interface that is used within the `ResponseTagger`
-  to provide the header name and the formatted tags header value.
+* Added `TagHeaderFormatter` interface that is used within the `ResponseTagger`
+  to provide the header name and for formatting the tags header value.
 
 ### Varnish
 
@@ -82,10 +82,10 @@ See also the [GitHub releases page](https://github.com/FriendsOfSymfony/FOSHttpC
 2.0.0-beta3
 -----------
 
-* **BC break:** The `ResponseTagger` now expects an instance of
-  `TagHeaderFormatter` instead of `TagCapable` as first argument.
-* **BC break:** The constant `Varnish::DEFAULT_HTTP_HEADER_CACHE_TAGS` has been
-  moved to ``TagHeaderFormatter::DEFAULT_HEADER_NAME``.
+* **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,15 +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`` (default: ``X-Cache-Tags``): Allows you to change the HTTP header
-  used for purge and ban requests. It is **NOT** related to response tagging! It
-  is possible to use different header names for both, the tagging process and the
-  ban/purge requests. 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,30 +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 takes an instance of ``TagHeaderFormatter`` as first
-argument which is responsible for providing the header name as well as formatting
-the provided tags into a proper header value. This library ships with a
-``CommaSeparatedTagHeaderFormatter`` which simply turns an array of tags into a
-comma-separated list. If you need a different behavior, provide your own implementation
-of the `TagHeaderFormatter`` interface.
-Just note: It's your responsibility to make sure, your proxy configuration matches
-the configuration of the ``ResponseTagger``::
+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;
-    use FOS\HttpCache\TagHeaderFormatter;
 
-    $tagHeaderFormatter = new CommaSeparatedTagHeaderFormatter('Header-Name');
-    $responseTagger = new ResponseTagger($tagHeaderFormatter);
+    $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,31 +175,33 @@ 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:
 
-.. warning::
+.. hint::
 
-    Note that by default, both, the header name for tagging using the response
-    tagger and the header name for Varnish's purge and ban requests are named
-    ``X-Cache-Tags``. You may, however, have different header names.
+    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:
 

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/Varnish.php

@@ -16,7 +16,6 @@
 use FOS\HttpCache\ProxyClient\Invalidation\PurgeCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\RefreshCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\TagCapable;
-use FOS\HttpCache\TagHeaderFormatter\TagHeaderFormatter;
 
 /**
  * Varnish HTTP cache invalidator.
@@ -38,6 +37,16 @@ class Varnish extends HttpProxyClient implements BanCapable, PurgeCapable, Refre
     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';
+
     /**
      * {@inheritdoc}
      */
@@ -133,7 +142,7 @@ protected function configureOptions()
     {
         $resolver = parent::configureOptions();
         $resolver->setDefaults([
-            'tags_header' => TagHeaderFormatter::DEFAULT_HEADER_NAME,
+            'tags_header' => self::DEFAULT_HTTP_HEADER_CACHE_TAGS,
             'header_length' => 7500,
             'default_ban_headers' => [],
         ]);

src/ResponseTagger.php

@@ -12,8 +12,10 @@
 namespace FOS\HttpCache;
 
 use FOS\HttpCache\Exception\InvalidTagException;
+use FOS\HttpCache\TagHeaderFormatter\CommaSeparatedTagHeaderFormatter;
 use FOS\HttpCache\TagHeaderFormatter\TagHeaderFormatter;
 use Psr\Http\Message\ResponseInterface;
+use Symfony\Component\OptionsResolver\Options;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 
 /**
@@ -43,27 +45,31 @@ class ResponseTagger
     private $tags = [];
 
     /**
-     * Create the response tagger with a tag capable proxy client and options.
+     * Create the response tagger with a tag header formatter and options.
      *
      * Supported options are:
      *
+     * - header_formatter (TagHeaderFormatter) Default: CommaSeparatedTagHeaderFormatter with default header name
      * - strict (bool) Default: false. If set to true, throws exception when adding empty tags
      *
-     * @param TagHeaderFormatter $headerFormatter
-     * @param array              $options
+     * @param array $options
      */
-    public function __construct(TagHeaderFormatter $headerFormatter, array $options = [])
+    public function __construct(array $options = [])
     {
-        $this->headerFormatter = $headerFormatter;
-
         $resolver = new OptionsResolver();
         $resolver->setDefaults([
+            // callback to avoid instantiating the formatter when its not needed
+            'header_formatter' => function (Options $options) {
+                return new CommaSeparatedTagHeaderFormatter();
+            },
             'strict' => false,
         ]);
 
+        $resolver->setAllowedTypes('header_formatter', TagHeaderFormatter::class);
         $resolver->setAllowedTypes('strict', 'bool');
 
         $this->options = $resolver->resolve($options);
+        $this->headerFormatter = $this->options['header_formatter'];
     }
 
     /**

src/TagHeaderFormatter/TagHeaderFormatter.php

@@ -18,6 +18,11 @@
  */
 interface TagHeaderFormatter
 {
+    /**
+     * Default name of the header to mark tags on responses.
+     *
+     * @var string
+     */
     const DEFAULT_HEADER_NAME = 'X-Cache-Tags';
 
     /**

tests/Unit/ResponseTaggerTest.php

@@ -19,6 +19,12 @@
 
 class ResponseTaggerTest extends \PHPUnit_Framework_TestCase
 {
+    public function testDefaultFormatter()
+    {
+        $tagger = new ResponseTagger();
+        $this->assertEquals('X-Cache-Tags', $tagger->getTagsHeaderName());
+    }
+
     public function testGetTagsHeaderValue()
     {
         $headerFormatter = \Mockery::mock(TagHeaderFormatter::class)
@@ -28,7 +34,7 @@ public function testGetTagsHeaderValue()
             ->andReturn('post-1,test_post')
             ->getMock();
 
-        $tagger = new ResponseTagger($headerFormatter);
+        $tagger = new ResponseTagger(['header_formatter' => $headerFormatter]);
         $this->assertFalse($tagger->hasTags());
         $tagger->addTags(['post-1', 'test,post']);
         $this->assertTrue($tagger->hasTags());
@@ -47,7 +53,7 @@ public function testTagResponseReplace()
             ->andReturn('FOS-Tags')
             ->getMock();
 
-        $tagger = new ResponseTagger($headerFormatter);
+        $tagger = new ResponseTagger(['header_formatter' => $headerFormatter]);
 
         $response = \Mockery::mock(ResponseInterface::class)
             ->shouldReceive('withHeader')
@@ -70,7 +76,7 @@ public function testTagResponseAdd()
             ->andReturn('FOS-Tags')
             ->getMock();
 
-        $tagger = new ResponseTagger($headerFormatter);
+        $tagger = new ResponseTagger(['header_formatter' => $headerFormatter]);
 
         $response = \Mockery::mock(ResponseInterface::class)
             ->shouldReceive('withAddedHeader')
@@ -88,7 +94,7 @@ public function testTagResponseNoTags()
             ->shouldReceive('getTagsHeaderValue')->never()
             ->getMock();
 
-        $tagger = new ResponseTagger($headerFormatter);
+        $tagger = new ResponseTagger(['header_formatter' => $headerFormatter]);
 
         $response = \Mockery::mock(ResponseInterface::class)
             ->shouldReceive('withHeader')->never()
@@ -102,14 +108,10 @@ public function testStrictEmptyTag()
     {
         $headerFormatter = new CommaSeparatedTagHeaderFormatter('FOS-Tags');
 
-        $tagHandler = new ResponseTagger($headerFormatter, ['strict' => true]);
+        $tagHandler = new ResponseTagger(['header_formatter' => $headerFormatter, 'strict' => true]);
 
-        try {
-            $tagHandler->addTags(['post-1', false]);
-            $this->fail('Expected exception');
-        } catch (InvalidTagException $e) {
-            // success
-        }
+        $this->setExpectedException(InvalidTagException::class);
+        $tagHandler->addTags(['post-1', false]);
     }
 
     public function testNonStrictEmptyTag()
@@ -121,7 +123,7 @@ public function testNonStrictEmptyTag()
             ->andReturn('post-1')
             ->getMock();
 
-        $tagHandler = new ResponseTagger($headerFormatter);
+        $tagHandler = new ResponseTagger(['header_formatter' => $headerFormatter]);
         $tagHandler->addTags(['post-1', false, null, '']);
         $this->assertTrue($tagHandler->hasTags());
         $this->assertEquals('post-1', $tagHandler->getTagsHeaderValue());