Add abstracted tag handling

Aims to allow support for tagging also on Symfomy HTTP Cache and
potentially other caches by limiting the feature to focus on only
tags and not any random header.

Closes #234

Author: André R

README.md

@@ -12,6 +12,9 @@ This library integrates your PHP applications with HTTP caching proxies such as
 Use this library to send invalidation requests from your application to the caching proxy
 and to test your caching and invalidation code against a Varnish setup.
 
+It does this by abstracting some caching concepts and attempting to make sure these
+can be supported across Varnish, Nginx and Symfony HTTP Cache.
+
 If you use Symfony2, have a look at the
 [FOSHttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle).
 The bundle provides the invalidator as a service, along with a number of
@@ -22,6 +25,7 @@ Features
 
 * Send [cache invalidation requests](http://foshttpcache.readthedocs.org/en/stable/cache-invalidator.html)
   with minimal impact on performance.
+* Cache tagging abstraction use of BAN with Varnish and allowing support for other caching proxies in the future.
 * Use the built-in support for [Varnish](http://foshttpcache.readthedocs.org/en/stable/varnish-configuration.html)
   3 and 4, [NGINX](http://foshttpcache.readthedocs.org/en/stable/nginx-configuration.html), the 
   [Symfony reverse proxy from the http-kernel component](http://foshttpcache.readthedocs.org/en/stable/symfony-cache-configuration.html)

src/CacheInvalidator.php

@@ -17,18 +17,19 @@
 use FOS\HttpCache\Exception\ProxyUnreachableException;
 use FOS\HttpCache\Exception\UnsupportedProxyOperationException;
 use FOS\HttpCache\ProxyClient\ProxyClientInterface;
+use FOS\HttpCache\ProxyClient\Invalidation\TagsInterface;
 use FOS\HttpCache\ProxyClient\Invalidation\BanInterface;
 use FOS\HttpCache\ProxyClient\Invalidation\PurgeInterface;
 use FOS\HttpCache\ProxyClient\Invalidation\RefreshInterface;
 use Symfony\Component\EventDispatcher\EventDispatcher;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
-use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 /**
  * Manages HTTP cache invalidation.
  *
  * @author David de Boer <[email protected]>
  * @author David Buchmann <[email protected]>
+ * @author André Rømcke <[email protected]>
  */
 class CacheInvalidator
 {
@@ -47,6 +48,11 @@ class CacheInvalidator
      */
     const INVALIDATE = 'invalidate';
 
+    /**
+     * Value to check support of invalidateTags operation.
+     */
+    const TAGS = 'tags';
+
     /**
      * @var ProxyClientInterface
      */
@@ -90,6 +96,8 @@ public function supports($operation)
                 return $this->cache instanceof RefreshInterface;
             case self::INVALIDATE:
                 return $this->cache instanceof BanInterface;
+            case self::TAGS:
+                return $this->cache instanceof TagsInterface;
             default:
                 throw new InvalidArgumentException('Unknown operation ' . $operation);
         }
@@ -197,6 +205,27 @@ public function invalidate(array $headers)
         return $this;
     }
 
+    /**
+     * Remove/Expire cache objects based on cache tags
+     *
+     * @see TagsInterface::tags()
+     *
+     * @param array $tags Tags that should be removed/expired from the cache
+     * @param string $tagsHeader Name of the HTTP header used to provide the tags
+     *
+     * @throws UnsupportedProxyOperationException If HTTP cache does not support Tags invalidation
+     *
+     * @return $this
+     */
+    public function invalidateTags(array $tags, $tagsHeader = 'X-Cache-Tags')
+    {
+        if (!$this->cache instanceof TagsInterface) {
+            throw UnsupportedProxyOperationException::cacheDoesNotImplement('Tags');
+        }
+        $this->cache->tags($tags, $tagsHeader);
+        return $this;
+    }
+
     /**
      * Invalidate URLs based on a regular expression for the URI, an optional
      * content type and optional limit to certain hosts.

src/Handler/TagHandler.php

@@ -12,13 +12,15 @@
 namespace FOS\HttpCache\Handler;
 
 use FOS\HttpCache\CacheInvalidator;
+use FOS\HttpCache\Exception\InvalidArgumentException;
 use FOS\HttpCache\Exception\UnsupportedProxyOperationException;
 
 /**
  * Handler for cache tagging.
  *
  * @author David de Boer <[email protected]>
  * @author David Buchmann <[email protected]>
+ * @author André Rømcke <[email protected]>
  */
 class TagHandler
 {
@@ -47,8 +49,8 @@ class TagHandler
      */
     public function __construct(CacheInvalidator $invalidator, $tagsHeader = 'X-Cache-Tags')
     {
-        if (!$invalidator->supports(CacheInvalidator::INVALIDATE)) {
-            throw UnsupportedProxyOperationException::cacheDoesNotImplement('BAN');
+        if (!$invalidator->supports(CacheInvalidator::TAGS)) {
+            throw UnsupportedProxyOperationException::cacheDoesNotImplement('Tags');
         }
         $this->invalidator = $invalidator;
         $this->tagsHeader = $tagsHeader;
@@ -107,7 +109,7 @@ public function addTags(array $tags)
      * tag header.
      *
      * The cache manager is told to invalidate all content with the specified
-     * tags. The invalidaton requests are sent to the caching proxy on kernel
+     * tags. The invalidation requests are sent to the caching proxy on kernel
      * termination (both for web requests and command runs). To immediately
      * send the invalidation request, call the CacheManager::flush() method.
      *
@@ -117,9 +119,14 @@ public function addTags(array $tags)
      */
     public function invalidateTags(array $tags)
     {
-        $tagExpression = sprintf('(%s)(,.+)?$', implode('|', array_map('preg_quote', $this->escapeTags($tags))));
-        $headers = [$this->tagsHeader => $tagExpression];
-        $this->invalidator->invalidate($headers);
+        if (empty($tags)) {
+            return $this;
+        }
+
+        $this->invalidator->invalidateTags(
+            $this->escapeTags($tags),
+            $this->tagsHeader
+        );
 
         return $this;
     }

src/ProxyClient/Invalidation/TagsInterface.php

@@ -0,0 +1,31 @@
+<?php
+
+/*
+ * This file is part of the FOSHttpCache package.
+ *
+ * (c) FriendsOfSymfony <http://friendsofsymfony.github.com/>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace FOS\HttpCache\ProxyClient\Invalidation;
+
+use FOS\HttpCache\ProxyClient\ProxyClientInterface;
+
+/**
+ * An HTTP cache that supports invalidation by a cache tag, that is, removing, or expiring
+ * objects from the cache tagged with a given tag or set of tags.
+ */
+interface TagsInterface extends ProxyClientInterface
+{
+    /**
+     * Remove/Expire cache objects based on cache tags
+     *
+     * @param array $tags Tags that should be removed/expired from the cache
+     * @param string $tagsHeader Name of the HTTP header used to provide the tags.
+     *
+     * @return $this
+     */
+    public function tags(array $tags, $tagsHeader = 'X-Cache-Tags');
+}

src/ProxyClient/Varnish.php

@@ -16,6 +16,7 @@
 use FOS\HttpCache\ProxyClient\Invalidation\BanInterface;
 use FOS\HttpCache\ProxyClient\Invalidation\PurgeInterface;
 use FOS\HttpCache\ProxyClient\Invalidation\RefreshInterface;
+use FOS\HttpCache\ProxyClient\Invalidation\TagsInterface;
 use FOS\HttpCache\ProxyClient\Request\InvalidationRequest;
 use FOS\HttpCache\ProxyClient\Request\RequestQueue;
 use Http\Adapter\HttpAdapter;
@@ -25,7 +26,7 @@
  *
  * @author David de Boer <[email protected]>
  */
-class Varnish extends AbstractProxyClient implements BanInterface, PurgeInterface, RefreshInterface
+class Varnish extends AbstractProxyClient implements BanInterface, PurgeInterface, RefreshInterface, TagsInterface
 {
     const HTTP_METHOD_BAN          = 'BAN';
     const HTTP_METHOD_PURGE        = 'PURGE';
@@ -86,6 +87,16 @@ public function setDefaultBanHeader($name, $value)
         $this->defaultBanHeaders[$name] = $value;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function tags(array $tags, $tagsHeader = 'X-Cache-Tags')
+    {
+        $tagExpression = sprintf('(%s)(,.+)?$', implode('|', array_map('preg_quote', $tags)));
+
+        return $this->ban([$tagsHeader => $tagExpression]);
+    }
+
     /**
      * {@inheritdoc}
      */

tests/Unit/CacheInvalidatorTest.php

@@ -34,6 +34,7 @@ public function testSupportsTrue()
         $this->assertTrue($cacheInvalidator->supports(CacheInvalidator::PATH));
         $this->assertTrue($cacheInvalidator->supports(CacheInvalidator::REFRESH));
         $this->assertTrue($cacheInvalidator->supports(CacheInvalidator::INVALIDATE));
+        $this->assertTrue($cacheInvalidator->supports(CacheInvalidator::TAGS));
     }
 
     public function testSupportsFalse()
@@ -45,6 +46,7 @@ public function testSupportsFalse()
         $this->assertFalse($cacheInvalidator->supports(CacheInvalidator::PATH));
         $this->assertFalse($cacheInvalidator->supports(CacheInvalidator::REFRESH));
         $this->assertFalse($cacheInvalidator->supports(CacheInvalidator::INVALIDATE));
+        $this->assertFalse($cacheInvalidator->supports(CacheInvalidator::TAGS));
     }
 
     /**
@@ -108,6 +110,23 @@ public function testInvalidate()
         $cacheInvalidator->invalidate($headers);
     }
 
+    public function testInvalidateTags()
+    {
+        $tags = [
+            'post-8',
+            'post-type-2'
+        ];
+
+        $tagHandler = \Mockery::mock('\FOS\HttpCache\ProxyClient\Invalidation\TagsInterface')
+            ->shouldReceive('tags')
+            ->with($tags, $tagsHeader = 'X-Cache-TRex')
+            ->once()
+            ->getMock();
+
+        $cacheInvalidator = new CacheInvalidator($tagHandler);
+        $cacheInvalidator->invalidateTags($tags, $tagsHeader);
+    }
+
     public function testInvalidateRegex()
     {
         $ban = \Mockery::mock('\FOS\HttpCache\ProxyClient\Invalidation\BanInterface')
@@ -148,6 +167,12 @@ public function testMethodException()
         } catch (UnsupportedProxyOperationException $e) {
             // success
         }
+        try {
+            $cacheInvalidator->invalidateTags([]);
+            $this->fail('Expected exception');
+        } catch (UnsupportedProxyOperationException $e) {
+            // success
+        }
     }
 
     /**

tests/Unit/Handler/TagHandlerTest.php

@@ -19,11 +19,11 @@ class TagHandlerTest extends \PHPUnit_Framework_TestCase
     public function testInvalidateTags()
     {
         $cacheInvalidator = \Mockery::mock('FOS\HttpCache\CacheInvalidator')
-            ->shouldReceive('invalidate')
-            ->with(['X-Cache-Tags' => '(post\-1|posts)(,.+)?$'])
+            ->shouldReceive('invalidateTags')
+            ->with(['post-1', 'posts'], 'X-Cache-Tags')
             ->once()
             ->shouldReceive('supports')
-            ->with(CacheInvalidator::INVALIDATE)
+            ->with(CacheInvalidator::TAGS)
             ->once()
             ->andReturn(true)
             ->getMock();
@@ -35,11 +35,11 @@ public function testInvalidateTags()
     public function testInvalidateTagsCustomHeader()
     {
         $cacheInvalidator = \Mockery::mock('FOS\HttpCache\CacheInvalidator')
-            ->shouldReceive('invalidate')
-            ->with(['Custom-Tags' => '(post\-1)(,.+)?$'])
+            ->shouldReceive('invalidateTags')
+            ->with(['post-1'], 'Custom-Tags')
             ->once()
             ->shouldReceive('supports')
-            ->with(CacheInvalidator::INVALIDATE)
+            ->with(CacheInvalidator::TAGS)
             ->once()
             ->andReturn(true)
             ->getMock();
@@ -52,11 +52,11 @@ public function testInvalidateTagsCustomHeader()
     public function testEscapingTags()
     {
         $cacheInvalidator = \Mockery::mock('FOS\HttpCache\CacheInvalidator')
-            ->shouldReceive('invalidate')
-            ->with(['X-Cache-Tags' => '(post_test)(,.+)?$'])
+            ->shouldReceive('invalidateTags')
+            ->with(['post_test'], 'X-Cache-Tags')
             ->once()
             ->shouldReceive('supports')
-            ->with(CacheInvalidator::INVALIDATE)
+            ->with(CacheInvalidator::TAGS)
             ->once()
             ->andReturn(true)
             ->getMock();
@@ -72,7 +72,7 @@ public function testInvalidateUnsupported()
     {
         $cacheInvalidator = \Mockery::mock('FOS\HttpCache\CacheInvalidator')
             ->shouldReceive('supports')
-            ->with(CacheInvalidator::INVALIDATE)
+            ->with(CacheInvalidator::TAGS)
             ->once()
             ->andReturn(false)
             ->getMock();
@@ -84,7 +84,7 @@ public function testTagResponse()
     {
         $cacheInvalidator = \Mockery::mock('FOS\HttpCache\CacheInvalidator')
             ->shouldReceive('supports')
-            ->with(CacheInvalidator::INVALIDATE)
+            ->with(CacheInvalidator::TAGS)
             ->once()
             ->andReturn(true)
             ->getMock();

tests/Unit/ProxyClient/VarnishTest.php

@@ -99,6 +99,28 @@ public function testBanPathEmptyHost()
         $varnish->banPath('/articles/.*', 'text/html', $hosts);
     }
 
+    public function testTagsHeaders()
+    {
+        $varnish = new Varnish(['127.0.0.1:123'], 'fos.lo', $this->client);
+        $varnish->setDefaultBanHeaders(
+            ['A' => 'B']
+        );
+        $varnish->setDefaultBanHeader('Test', '.*');
+        $varnish->tags(['post-1', 'post-type-3'], 'X-Cache-Tags')->flush();
+
+        $requests = $this->getRequests();
+
+        $this->assertCount(1, $requests);
+        $this->assertEquals('BAN', $requests[0]->getMethod());
+
+        $this->assertEquals('(post\-1|post\-type\-3)(,.+)?$', $requests[0]->getHeaderLine('X-Cache-Tags'));
+        $this->assertEquals('fos.lo', $requests[0]->getHeaderLine('Host'));
+
+        // This being taken into account, might not be expected from user POV?
+        $this->assertEquals('.*', $requests[0]->getHeaderLine('Test'));
+        $this->assertEquals('B', $requests[0]->getHeaderLine('A'));
+    }
+
     public function testPurge()
     {
         $ips = ['127.0.0.1:8080', '123.123.123.2'];
@@ -142,7 +164,7 @@ protected function setUp()
     }
 
     /**
-     * @return array|RequestInterface[]
+     * @return array|\Psr\Http\Message\RequestInterface[]
      */
     protected function getRequests()
     {