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: andrerom

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 HttpCache.
+
 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, uses BAN with Varnish and allows tagging 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
+     *
+     * @throws UnsupportedProxyOperationException If HTTP cache does not support Tags invalidation
+     *
+     * @return $this
+     */
+    public function invalidateTags(array $tags)
+    {
+        if (!$this->cache instanceof TagsInterface) {
+            throw UnsupportedProxyOperationException::cacheDoesNotImplement('Tags');
+        }
+        $this->cache->invalidateTags($tags);
+
+        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

@@ -150,4 +150,23 @@ private function handleErrorResponses(array $responses)
 
         return $exceptions;
     }
+
+    /**
+     * Make sure that the tags are valid.
+     *
+     * Reusable function for proxy clients.
+     * Escapes `,` and `\n` (newline) characters.
+     *
+     * @param array $tags The tags to escape.
+     *
+     * @return array Sane tags.
+     */
+    protected function escapeTags(array $tags)
+    {
+        array_walk($tags, function (&$tag) {
+            $tag = str_replace([',', "\n"], ['_', '_'], $tag);
+        });
+
+        return $tags;
+    }
 }

src/ProxyClient/AbstractProxyClient.php

@@ -0,0 +1,48 @@
+<?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
+     *
+     * @return $this
+     */
+    public function invalidateTags(array $tags);
+
+    /**
+     * Get the value for the HTTP tag header.
+     *
+     * This concatenates all tags and ensures correct encoding.
+     *
+     * @param array $tags
+     *
+     * @return string
+     */
+    public function getTagsHeaderValue(array $tags);
+
+    /**
+     * Get the HTTP header name that will hold cache tags.
+     *
+     * @return string
+     */
+    public function getTagsHeaderName();
+}

src/ProxyClient/Invalidation/TagsInterface.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';
@@ -52,16 +53,23 @@ class Varnish extends AbstractProxyClient implements BanInterface, PurgeInterfac
      */
     private $baseUriSet;
 
+    /**
+     * @var string
+     */
+    private $tagsHeader;
+
     /**
      * {@inheritdoc}
      */
     public function __construct(
         array $servers,
         $baseUri = null,
-        HttpAdapter $httpAdapter = null
+        HttpAdapter $httpAdapter = null,
+        $tagsHeader = 'X-Cache-Tags'
     ) {
         parent::__construct($servers, $baseUri, $httpAdapter);
         $this->baseUriSet = $baseUri !== null;
+        $this->tagsHeader = $tagsHeader;
     }
 
     /**
@@ -86,6 +94,34 @@ public function setDefaultBanHeader($name, $value)
         $this->defaultBanHeaders[$name] = $value;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function invalidateTags(array $tags)
+    {
+        $tagExpression = sprintf('(%s)(,.+)?$', implode('|', array_map('preg_quote', $this->escapeTags($tags))));
+
+        return $this->ban([$this->tagsHeader => $tagExpression]);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getTagsHeaderValue(array $tags)
+    {
+        return implode(',', array_unique($this->escapeTags($tags)));
+    }
+
+    /**
+     * Get the HTTP header name that will hold cache tags.
+     *
+     * @return string
+     */
+    public function getTagsHeaderName()
+    {
+        return $this->tagsHeader;
+    }
+
     /**
      * {@inheritdoc}
      */