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.
+
+By taking advantage of :doc:`response tagging <response-tagging>`, invalidation
+all URLs that has been tagged with a given tag becomes possible.
+
+
+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/proxy-clients.rst

@@ -91,6 +91,11 @@ include that port in the base URL::
 
     $varnish = new Varnish($servers, 'my-cool-app.com:8080');
 
+Another optional parameter available on Varnish client is ``tagsHeader``, which allows you to
+change the default HTTP header used for tags, ``X-Cache-Tags``::
+
+    $varnish = new Varnish($servers, 'example.com', $adapter, 'X-Custom-Tags-Header');
+
 .. note::
 
     To make invalidation work, you need to :doc:`configure Varnish <varnish-configuration>` accordingly.

doc/invalidation-handlers.rst renamed to doc/response-tagging.rst

@@ -1,17 +1,17 @@
-Extra Invalidation Handlers
-===========================
+Response Tagging
+================
 
-This library provides decorators that build on top of the ``CacheInvalidator``
-to simplify common operations.
+This library provides a service to handle tagging of responses ``ResponseTagger``
+to simplify use of tags.
 
 .. _tags:
 
-Tag Handler
------------
+Response Tagger
+---------------
 
-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``.
+The ResponseTagger helps you to mark responses with tags that you can later use to
+invalidate all cache entries with that tag. Response Tagging and tag invalidation
+require a proxy client that implements ``TagsInterface``.
 
 Setup
 ~~~~~
@@ -20,29 +20,28 @@ Setup
 
     Make sure to :doc:`configure your proxy <proxy-configuration>` for tagging first.
 
-The tag handler is a decorator around the ``CacheInvalidator``. After
-:doc:`creating the invalidator <cache-invalidator>` with a proxy client
-that implements the ``BanInterface``, instantiate the ``TagHandler``::
+The response tagger is a decorator around a proxy client that implements
+the ``TagsInterface``, handling tags for the current response::
 
-    use FOS\HttpCache\Handler\TagHandler;
+    use FOS\HttpCache\ResponseTagger;
 
-    // $cacheInvalidator already created as instance of FOS\HttpCache\CacheInvalidator
-    $tagHandler = new TagHandler($cacheInvalidator);
+    // $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 handler using::
+correct tags on all responses. You can add tags to the response using::
 
-    $tagHandler->addTags(['tag-two', 'group-a']);
+    $responseTagger->addTags(['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()
+        $responseTagger->getTagsHeaderName(),
+        $responseTagger->getTagsHeaderValue()
     );
 
 .. tip::
@@ -75,21 +74,21 @@ Only ``/one`` will stay in the cache.
 
 .. note::
 
-    Don't forget to call :ref:`flush <flush>` on the ``CacheInvalidator`` to commit the invalidations
-    to the caching proxy.
-
-.. _custom_tags_header:
+    For further reading on tag invalidation see :doc:`cache-invalidator page <cache-invalidator>`.
+    For changing the cache header, :doc:`configure your proxy <proxy-clients>`
 
 Custom Tags Header
 ~~~~~~~~~~~~~~~~~~
 
+// TOOO: Move or change to reflect that this depends on Proxy Client.
+
 Tagging uses a custom HTTP header to identify tags. You can change the default
 header ``X-Cache-Tags`` in the constructor::
 
-    use FOS\HttpCache\Handler\TagHandler;
+    use FOS\HttpCache\ResponseTagger;
 
     // $cacheInvalidator already created as instance of FOS\HttpCache\CacheInvalidator
-    $tagHandler = new TagHandler($cacheInvalidator, 'My-Cache-Header');
+    $responseTagger = new ResponseTagger($cacheInvalidator, 'My-Cache-Header');
 
 Make sure to reflect this change in your
 :doc:`caching proxy configuration <proxy-configuration>`.