Merge pull request #237 from andrerom/tags

Add abstracted tag handling

Author: dbu

CHANGELOG.md

@@ -18,6 +18,8 @@ See also the [GitHub releases page](https://github.com/FriendsOfSymfony/FOSHttpC
   caching proxy.
 * Refactored the proxy client test system into traits. Removed ProxyTestCase,
   use the traits `CacheAssertions` and `HttpCaller` instead.
+* Abstracting tags by adding new `TagsInterface` for ProxyClients, as part of that also:
+  BC break: Moved tag invalidation to `CacheInvalidator`, and rename TagHandler to ResponseTagger.
 
 1.4.0
 -----

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)

doc/cache-invalidator.rst

@@ -82,6 +82,32 @@ Refresh a URL with added header(s)::
 
 .. _invalidate regex:
 
+
+Invalidating by Tags
+--------------------
+
+.. note::
+
+    Make sure to :doc:`configure your proxy <proxy-configuration>` for tagging first,
+    in the case of Varnish this is powered by banning.
+
+When you are using :doc:`response tagging <response-tagging>`, you can invalidate
+all responses that where tagged with a specific label.
+
+Invalidate a tag::
+
+    $cacheInvalidator->invalidateTags(['blog-post-44'])->flush();
+
+See below for the :ref:`flush() <flush>` method.
+
+Invalidate several tags::
+
+    $cacheInvalidator
+        ->invalidateTags(['type-65', 'location-3'])
+        ->flush()
+    ;
+
+
 Invalidating With a Regular Expression
 --------------------------------------
 

doc/index.rst

@@ -28,7 +28,7 @@ Contents:
     proxy-configuration
     proxy-clients
     cache-invalidator
-    invalidation-handlers
+    response-tagging
     user-context
 
     testing-your-application

doc/invalidation-handlers.rst

@@ -91,6 +91,15 @@ include that port in the base URL::
 
     $varnish = new Varnish($servers, 'my-cool-app.com:8080');
 
+.. _varnish_custom_tags_header:
+
+Another optional parameter available on Varnish client is ``tagsHeader``, which allows you to
+change the default HTTP header used for tagging, ``X-Cache-Tags``::
+
+    $varnish = new Varnish($servers, 'example.com', $adapter, 'X-Custom-Tags-Header');
+
+ Make sure to reflect this change in your :doc:`caching proxy configuration <proxy-configuration>`.
+
 .. note::
 
     To make invalidation work, you need to :doc:`configure Varnish <varnish-configuration>` accordingly.
@@ -267,5 +276,6 @@ Varnish client::
 Make sure to add any headers that you want to ban on to your
 :doc:`proxy configuration <proxy-configuration>`.
 
+.. _header: http://php.net/header
 .. _HTTP Adapter: http://php-http.readthedocs.org/en/latest/
 .. _PSR-7 message implementation: https://packagist.org/providers/psr/http-message-implementation

doc/proxy-clients.rst

@@ -0,0 +1,76 @@
+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
+entries with that tag.
+
+.. _tags:
+
+Setup
+~~~~~
+
+.. note::
+
+    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 ``TagsInterface``, handling adding tags to responses::
+
+    use FOS\HttpCache\ResponseTagger;
+
+    // $proxyClient already created, implementing FOS\HttpCache\ProxyClient\Invalidation\TagsInterface
+    $responseTagger = new ResponseTagger($proxyClient);
+
+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. You can add tags to the response using::
+
+    $responseTagger->addTags(['tag-two', 'group-a']);
+
+Before any content is sent out, you need to send the tag header_::
+
+    header(sprintf('%s: %s'),
+        $responseTagger->getTagsHeaderName(),
+        $responseTagger->getTagsHeaderValue()
+    );
+
+.. tip::
+
+    If you are using Symfony with the FOSHttpCacheBundle_, the tags
+    added to ``ResponseTagger`` are added to the response automatically.
+    You also have `additional methods of defining tags`_ with
+    annotations and on URL patterns.
+
+Assume you sent four responses:
+
++------------+-------------------------+
+| Response:  | ``X-Cache-Tags`` header:|
++============+=========================+
+| ``/one``   | ``tag-one``             |
++------------+-------------------------+
+| ``/two``   | ``tag-two, group-a``    |
++------------+-------------------------+
+| ``/three`` | ``tag-three, group-a``  |
++------------+-------------------------+
+| ``/four``  | ``tag-four, group-b``   |
++------------+-------------------------+
+
+You can now invalidate some URLs using tags::
+
+    $tagHandler->invalidateTags(['group-a', 'tag-four'])->flush();
+
+This will ban all requests having either the tag ``group-a`` /or/ ``tag-four``.
+In the above example, this will invalidate ``/two``, ``/three`` and ``/four``.
+Only ``/one`` will stay in the cache.
+
+.. note::
+
+    For further reading on tag invalidation see :doc:`cache-invalidator page <cache-invalidator>`.
+    For changing the cache header, :doc:`configure your proxy <proxy-clients>`.
+
+.. _header: http://php.net/header
+.. _additional methods of defining tags: http://foshttpcachebundle.readthedocs.org/en/latest/features/tagging.html

doc/response-tagging.rst

@@ -180,7 +180,7 @@ using an ``X-Cache-Tags`` header.
 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 <custom_tags_header>`. Your custom
+:ref:`configured in the cache invalidator <varnish_custom_tags_header>`. Your custom
 VCL will look like this:
 
 .. configuration-block::

doc/varnish-configuration.rst

@@ -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.