cleanup documenation, keep InvalidateTagCommand BC

Author: dbu

Resources/doc/conf.py

@@ -56,9 +56,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.0.0'
+version = '1.3.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.0'
+release = '1.3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

Resources/doc/features/tagging.rst

@@ -38,51 +38,27 @@ annotations.
 Tagging from code
 ~~~~~~~~~~~~~~~~~
 
-Inject the ``CacheManager`` (service ``fos_http_cache.cache_manager``) and
-use ``tagResponse($response, $tags)`` to set tags on a response::
+Inject the ``TagHandler`` (service ``fos_http_cache.handler.tag_handler``) and
+use ``addTags($tags)`` to add tags that will be set on the response::
 
-    use Symfony\Component\HttpFoundation\Response;
-    use FOS\HttpCacheBundle\CacheManager;
+    use FOS\HttpCacheBundle\Handler\TagHandler;
 
     class NewsController
     {
         /**
-         * @var CacheManager
+         * @var TagHandler
          */
-        private $cacheManager;
+        private $tagHandler;
 
         public function articleAction($id)
         {
-            $response = new Response('Some news article');
-            $this->cacheManager->tagResponse($response, array('news', 'news-' . $id));
-
-            return $response;
-        }
-    }
-
-If you have no access to the ``Response`` object (e.g. because it is not
-created yet), inject the ``TagSubscriber`` (service ``fos_http_cache.event_listener.tag``)
-and call ``addTags($tags)`` to set tags that will be added to the response once
-it exists::
-
-    use FOS\HttpCacheBundle\EventListener\TagSubscriber;
-
-    class Service
-    {
-        /**
-         * @var TagSubscriber
-         */
-        private $tagSubscriber;
-
-        public function doStuff($thing)
-        {
-            $this->tagSubscriber->addTags(array('news', 'news-' . $thing->getId()));
+            $this->tagHandler->addTags(array('news', 'news-' . $id));
 
             // ...
         }
     }
 
-To invalidate tags, call ``CacheManager::invalidateTags($tags)``::
+To invalidate tags, call ``TagHandler::invalidateTags($tags)``::
 
     class NewsController
     {
@@ -92,13 +68,13 @@ To invalidate tags, call ``CacheManager::invalidateTags($tags)``::
         {
             // ...
 
-            $this->cacheManager->invalidateTags(array('news-' . $id))->flush();
+            $this->tagHandler->invalidateTags(array('news-' . $id));
 
             // ...
         }
     }
 
-See the :ref:`Cache Manager reference <cache_manager_tags>` for full details.
+See the :ref:`Tag Handler reference <tag_handler_addtags>` for full details.
 
 Configuration
 ~~~~~~~~~~~~~

Resources/doc/reference.rst

@@ -10,4 +10,5 @@ annotations and public methods.
     reference/configuration
     reference/annotations
     reference/cache-manager
+    reference/tag-handler
     reference/glossary

Resources/doc/reference/cache-manager.rst

@@ -82,31 +82,12 @@ Refresh a Route::
 
 .. _cache_manager_tags:
 
-``tagResponse()``
------------------
+``tagResponse()``, ``invalidateTags()``
+---------------------------------------
 
-Use the Cache Manager to tag responses::
-
-    // $response is a \Symfony\Component\HttpFoundation\Response object
-    $cacheManager->tagResponse($response, array('some-tag', 'other-tag'));
-
-The tags are appended to already existing tags, unless you set the ``$replace``
-option to true::
-
-    $cacheManager->tagResponse($response, array('different'), true);
-
-.. tip::
-
-    If you do not yet have the response available, you can use the
-    ``TagSubscriber::addTags($tags)`` method to have your tags added once the
-    response is being sent.
-
-``invalidateTags()``
---------------------
-
-Invalidate cache tags::
-
-    $cacheManager->invalidateTags(array('some-tag', 'other-tag'));
+..versionadded:: 1.3
+    Since version 1.3, use the :ref:`TagHandler <tag-handler>` instead of the
+    CacheManager for working with tags.
 
 .. _flushing:
 

Resources/doc/reference/tag-handler.rst

@@ -0,0 +1,28 @@
+The Tag Handler
+===============
+
+Service to work with :doc:`Cache Tagging <../features/tagging>`. You can add tags to the
+handler and generate invalidation requests that are queued in the invalidator.
+
+A response listener checks the ``TagHandler`` to detect tags that need to be
+set on a response. As with other invalidation operations, invalidation requests
+are flushed to the caching proxy :ref:`after the response has been sent <flushing>`.
+
+.. _tag_handler_addtags:
+
+``addTags()``
+-------------
+
+Add tags to be sent with the response::
+
+    $tagHandler->addTags(array('some-tag', 'other-tag'));
+
+This method can be called regardless of whether the response object already
+exists or not.
+
+``invalidateTags()``
+--------------------
+
+Invalidate cache tags::
+
+    $tagHandler->invalidateTags(array('some-tag', 'other-tag'));