Change doc for abstract tag changes

Author: andrerom

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

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