addTags on TagHandler

doc/_static/fos.css

@@ -0,0 +1,3 @@
+.versionmodified {
+    font-weight: bold;
+}

doc/conf.py

@@ -132,6 +132,7 @@
 def setup(app):
     app.add_javascript('tabs.js')
     app.add_stylesheet('tabs.css')
+    app.add_stylesheet('fos.css')
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

doc/invalidation-handlers.rst

@@ -9,9 +9,14 @@ to simplify common operations.
 Tag Handler
 -----------
 
-The tag handler helps you to invalidate all cache entries that where marked
-with a specified tag. It works only with a ``CacheInvalidator`` that supports
-``CacheInvalidator::INVALIDATE``.
+.. versionadded:: 1.3
+    The tag handler was added in FOSHttpCache 1.3. If you are using an older
+    version of the library and can not update, you need to use
+    ``CacheInvalidator::invalidateTags``.
+
+The tag handler helps you to mark responses with tags that you can later use to
+invalidate all cache entries with that tag. Tag invalidation works only with a
+``CacheInvalidator`` that supports ``CacheInvalidator::INVALIDATE``.
 
 Setup
 ~~~~~
@@ -34,8 +39,22 @@ Usage
 
 With tags you can group related representations so it becomes easier to
 invalidate them. You will have to make sure your web application adds the
-correct tags on all responses by setting the ``X-Cache-Tags`` header. The
-FOSHttpCacheBundle_ does this for you when you’re using Symfony.
+correct tags on all responses. You can add tags to the handler using::
+
+    $tagHandler->addTags(array('tag-two', 'group-a'));
+
+Before any content is sent out, you need to send the tag header_::
+
+    header(sprintf('%s: %s'),
+        $tagHandler->getTagsHeaderName(),
+        $tagHandler->getTagsHeaderValue()
+    );
+
+.. tip::
+
+    If you are using Symfony with the FOSHttpCacheBundle_, the tag header is
+    set automatically. You also have `additional methods of defining tags`_ with
+    annotations and on URL patterns.
 
 Assume you sent four responses:
 
@@ -74,3 +93,6 @@ header ``X-Cache-Tags`` in the constructor::
 
 Make sure to reflect this change in your
 :doc:`caching proxy configuration <proxy-configuration>`.
+
+.. _header: http://php.net/header
+.. _additional methods of defining tags: http://foshttpcachebundle.readthedocs.org/en/latest/features/tagging.html

src/CacheInvalidator.php

@@ -160,7 +160,7 @@ public function addSubscriber(EventSubscriberInterface $subscriber)
      */
     public function setTagsHeader($tagsHeader)
     {
-        if ($this->tagHandler && $this->tagsHeader !== $tagsHeader) {
+        if ($this->tagHandler && $this->tagHandler->getTagsHeaderName() !== $tagsHeader) {
             $this->tagHandler = new TagHandler($this, $tagsHeader);
         }
 
@@ -172,11 +172,11 @@ public function setTagsHeader($tagsHeader)
      *
      * @return string
      *
-     * @deprecated Use TagHandler::getTagsHeader instead.
+     * @deprecated Use TagHandler::getTagsHeaderName instead.
      */
     public function getTagsHeader()
     {
-        return $this->tagsHeader;
+        return $this->tagHandler ? $this->tagHandler->getTagsHeaderName() : $this->tagsHeader;
     }
 
     /**

src/Handler/TagHandler.php

@@ -32,6 +32,11 @@ class TagHandler
      */
     private $tagsHeader;
 
+    /**
+     * @var array
+     */
+    private $tags = array();
+
     /**
      * Constructor
      *
@@ -49,6 +54,40 @@ public function __construct(CacheInvalidator $invalidator, $tagsHeader = 'X-Cach
         $this->tagsHeader = $tagsHeader;
     }
 
+    /**
+     * Get the HTTP header name that will hold cache tags.
+     *
+     * @return string
+     */
+    public function getTagsHeaderName()
+    {
+        return $this->tagsHeader;
+    }
+
+    /**
+     * Get the value for the HTTP tag header.
+     *
+     * This concatenates all tags and ensures correct encoding.
+     *
+     * @return string
+     */
+    public function getTagsHeaderValue()
+    {
+        return implode(',', array_unique($this->escapeTags($this->tags)));
+    }
+
+    /**
+     * Add tags to be sent.
+     *
+     * This must be called before any response is sent to the client.
+     *
+     * @param array $tags List of tags to add.
+     */
+    public function addTags(array $tags)
+    {
+        $this->tags = array_merge($this->tags, $tags);
+    }
+
     /**
      * Invalidate cache entries that contain any of the specified tags in their
      * tag header.
@@ -59,10 +98,26 @@ public function __construct(CacheInvalidator $invalidator, $tagsHeader = 'X-Cach
      */
     public function invalidateTags(array $tags)
     {
-        $tagExpression = sprintf('(%s)(,.+)?$', implode('|', array_map('preg_quote', $tags)));
+        $tagExpression = sprintf('(%s)(,.+)?$', implode('|', array_map('preg_quote', $this->escapeTags($tags))));
         $headers = array($this->tagsHeader => $tagExpression);
         $this->invalidator->invalidate($headers);
 
         return $this;
     }
+
+    /**
+     * Make sure that the tags are valid.
+     *
+     * @param array $tags The tags to escape.
+     *
+     * @return array Sane tags.
+     */
+    protected function escapeTags(array $tags)
+    {
+        array_walk($tags, function (&$tag) {
+            $tag = str_replace(array(',', "\n"), array('_', '_'), $tag);
+        });
+
+        return $tags;
+    }
 }

tests/Unit/Handler/TagHandlerTest.php

@@ -45,9 +45,26 @@ public function testInvalidateTagsCustomHeader()
             ->getMock();
 
         $tagHandler = new TagHandler($cacheInvalidator, 'Custom-Tags');
+        $this->assertEquals('Custom-Tags', $tagHandler->getTagsHeaderName());
         $tagHandler->invalidateTags(array('post-1'));
     }
 
+    public function testEscapingTags()
+    {
+        $cacheInvalidator = \Mockery::mock('FOS\HttpCache\CacheInvalidator')
+            ->shouldReceive('invalidate')
+            ->with(array('X-Cache-Tags' => '(post_test)(,.+)?$'))
+            ->once()
+            ->shouldReceive('supports')
+            ->with(CacheInvalidator::INVALIDATE)
+            ->once()
+            ->andReturn(true)
+            ->getMock();
+
+        $tagHandler = new TagHandler($cacheInvalidator);
+        $tagHandler->invalidateTags(array('post,test'));
+    }
+
     /**
      * @expectedException \FOS\HttpCache\Exception\UnsupportedProxyOperationException
      */
@@ -62,4 +79,18 @@ public function testInvalidateUnsupported()
 
         new TagHandler($cacheInvalidator);
     }
+
+    public function testTagResponse()
+    {
+        $cacheInvalidator = \Mockery::mock('FOS\HttpCache\CacheInvalidator')
+            ->shouldReceive('supports')
+            ->with(CacheInvalidator::INVALIDATE)
+            ->once()
+            ->andReturn(true)
+            ->getMock();
+
+        $tagHandler = new TagHandler($cacheInvalidator);
+        $tagHandler->addTags(array('post-1', 'test,post'));
+        $this->assertEquals('post-1,test_post', $tagHandler->getTagsHeaderValue());
+    }
 }