Have a method to add tags to the TagSubscriber directly, for when the request does not exist yet

Author: dbu

CHANGELOG.md

@@ -4,6 +4,14 @@ Changelog
 1.3.0
 -----
 
+* **2015-05-08** Configured/annotated cache tags on subrequests
+  (twig `render(controller())`) are no longer ignored. Additionally, it is now
+  possible to add tags from code before the response object has been created,
+  by using the TagHandler.
+  If you defined custom services for the `InvalidateTagCommand`, you should
+  now inject the TagHandler instead of the CacheManager.
+
+  **deprecated** `CacheManager::tagResponse` in favor of `TagHandler::addTags`
 * **2015-05-08** Added configuration option for custom proxy client (#208)
 
 1.2.0

CacheManager.php

@@ -67,6 +67,8 @@ public function setGenerateUrlType($generateUrlType)
      *                           response
      *
      * @return $this
+     *
+     * @deprecated Add tags with TagHandler::addTags and then use TagHandler::tagResponse
      */
     public function tagResponse(Response $response, array $tags, $replace = false)
     {

Command/InvalidateTagCommand.php

@@ -11,18 +11,25 @@
 
 namespace FOS\HttpCacheBundle\Command;
 
+use FOS\HttpCacheBundle\CacheManager;
+use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Input\InputArgument;
-use FOS\HttpCacheBundle\CacheManager;
+use FOS\HttpCache\Handler\TagHandler;
 
 /**
  * A command to trigger cache invalidation by tag from the command line.
  *
  * @author David Buchmann <[email protected]>
  */
-class InvalidateTagCommand extends BaseInvalidateCommand
+class InvalidateTagCommand extends ContainerAwareCommand
 {
+    /**
+     * @var TagHandler
+     */
+    private $tagHandler;
+
     /**
      * @var string
      */
@@ -32,13 +39,24 @@ class InvalidateTagCommand extends BaseInvalidateCommand
      * If no cache manager is specified explicitly, fos_http_cache.cache_manager
      * is automatically loaded.
      *
-     * @param CacheManager|null $cacheManager The cache manager to talk to.
-     * @param string            $commandName  Name of this command, in case you want to reuse it.
+     * Passing CacheManager as argument is deprecated and will be restricted to TagHandler in 2.0.
+     *
+     * @param TagHandler|CacheManager|null $tagHandler  The tag handler to talk to.
+     * @param string                       $commandName Name of this command, in case you want to reuse it.
      */
-    public function __construct(CacheManager $cacheManager = null, $commandName = 'fos:httpcache:invalidate:tag')
+    public function __construct($tagHandler = null, $commandName = 'fos:httpcache:invalidate:tag')
     {
+        if (!($tagHandler instanceof TagHandler || $tagHandler instanceof CacheManager || null === $tagHandler)) {
+            throw new \InvalidArgumentException(
+                sprintf(
+                    'Expected instance of TagHandler, CacheManager or null, but got %s',
+                    get_class($tagHandler)
+                )
+            );
+        }
         $this->commandName = $commandName;
-        parent::__construct($cacheManager);
+        $this->tagHandler = $tagHandler;
+        parent::__construct();
     }
 
     /**
@@ -72,6 +90,18 @@ protected function execute(InputInterface $input, OutputInterface $output)
     {
         $tags = $input->getArgument('tags');
 
-        $this->getCacheManager()->invalidateTags($tags);
+        $this->getTagManager()->invalidateTags($tags);
+    }
+
+    /**
+     * @return TagHandler|CacheManager
+     */
+    protected function getTagManager()
+    {
+        if (!$this->tagHandler) {
+            $this->tagHandler = $this->getContainer()->get('fos_http_cache.handler.tag_handler');
+        }
+
+        return $this->tagHandler;
     }
 }

DependencyInjection/FOSHttpCacheExtension.php

@@ -87,6 +87,7 @@ public function load(array $configs, ContainerBuilder $container)
         $container->setParameter($this->getAlias().'.compiler_pass.tag_annotations', $config['tags']['enabled']);
         if ($config['tags']['enabled']) {
             // true or auto
+            $container->setParameter($this->getAlias().'.tag_handler.header', $config['tags']['header']);
             $loader->load('tag_listener.xml');
             if (!empty($config['tags']['rules'])) {
                 $this->loadTagRules($container, $config['tags']['rules']);

EventListener/TagSubscriber.php

@@ -11,11 +11,12 @@
 
 namespace FOS\HttpCacheBundle\EventListener;
 
-use FOS\HttpCacheBundle\CacheManager;
+use FOS\HttpCacheBundle\Handler\TagHandler;
 use FOS\HttpCacheBundle\Configuration\Tag;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
+use Symfony\Component\HttpKernel\HttpKernelInterface;
 use Symfony\Component\HttpKernel\KernelEvents;
 use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
 
@@ -27,9 +28,9 @@
 class TagSubscriber extends AbstractRuleSubscriber implements EventSubscriberInterface
 {
     /**
-     * @var CacheManager
+     * @var TagHandler
      */
-    private $cacheManager;
+    private $tagHandler;
 
     /**
      * @var ExpressionLanguage
@@ -39,14 +40,14 @@ class TagSubscriber extends AbstractRuleSubscriber implements EventSubscriberInt
     /**
      * Constructor
      *
-     * @param CacheManager            $cacheManager
+     * @param TagHandler              $tagHandler
      * @param ExpressionLanguage|null $expressionLanguage
      */
     public function __construct(
-        CacheManager $cacheManager,
+        TagHandler $tagHandler,
         ExpressionLanguage $expressionLanguage = null
     ) {
-        $this->cacheManager = $cacheManager;
+        $this->tagHandler = $tagHandler;
         $this->expressionLanguage = $expressionLanguage;
     }
 
@@ -65,32 +66,28 @@ public function onKernelResponse(FilterResponseEvent $event)
         $response = $event->getResponse();
 
         $tags = array();
-
         // Only set cache tags or invalidate them if response is successful
         if ($response->isSuccessful()) {
             $tags = $this->getAnnotationTags($request);
         }
 
         $configuredTags = $this->matchRule($request, $response);
         if ($configuredTags) {
-            foreach ($configuredTags['tags'] as $tag) {
-                $tags[] = $tag;
-            }
+            $tags = array_merge($tags, $configuredTags['tags']);
             foreach ($configuredTags['expressions'] as $expression) {
                 $tags[] = $this->evaluateTag($expression, $request);
             }
         }
 
-        if (!count($tags)) {
-            return;
-        }
-
         if ($request->isMethodSafe()) {
-            // For safe requests (GET and HEAD), set cache tags on response
-            $this->cacheManager->tagResponse($response, $tags);
-        } else {
+            $this->tagHandler->addTags($tags);
+            if (HttpKernelInterface::MASTER_REQUEST === $event->getRequestType()) {
+                // For safe requests (GET and HEAD), set cache tags on response
+                $this->tagHandler->tagResponse($response);
+            }
+        } elseif (count($tags)) {
             // For non-safe methods, invalidate the tags
-            $this->cacheManager->invalidateTags($tags);
+            $this->tagHandler->invalidateTags($tags);
         }
     }
 

Handler/TagHandler.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace FOS\HttpCacheBundle\Handler;
+
+use FOS\HttpCache\Handler\TagHandler as BaseTagHandler;
+use Symfony\Component\HttpFoundation\Response;
+
+class TagHandler extends BaseTagHandler
+{
+    /**
+     * Tag response with the previously added tags.
+     *
+     * @param Response $response
+     * @param bool     $replace  Whether to replace the current tags on the
+     *                           response. If false, parses the header to merge
+     *                           tags.
+     *
+     * @return $this
+     */
+    public function tagResponse(Response $response, $replace = false)
+    {
+        if (!$replace && $response->headers->has($this->getTagsHeaderName())) {
+            $header = $response->headers->get($this->getTagsHeaderName());
+            if ('' !== $header) {
+                $this->addTags(explode(',', $response->headers->get($this->getTagsHeaderName())));
+            }
+        }
+
+        if ($this->hasTags()) {
+            $response->headers->set($this->getTagsHeaderName(), $this->getTagsHeaderValue());
+        }
+
+        return $this;
+    }
+}

Resources/config/cache_manager.xml

@@ -45,7 +45,7 @@
         </service>
 
         <service id="fos_http_cache.command.invalidate_tag" class="%fos_http_cache.command.invalidate_tag.class%">
-            <argument type="service" id="fos_http_cache.cache_manager" />
+            <argument type="service" id="fos_http_cache.handler.tag_handler" />
             <tag name="console.command"/>
         </service>
 

Resources/config/tag_listener.xml

@@ -9,9 +9,14 @@
     </parameters>
 
     <services>
+        <service id="fos_http_cache.handler.tag_handler" class="FOS\HttpCacheBundle\Handler\TagHandler">
+            <argument type="service" id="fos_http_cache.cache_manager"/>
+            <argument>%fos_http_cache.tag_handler.header%</argument>
+        </service>
+
         <service id="fos_http_cache.event_listener.tag"
                  class="%fos_http_cache.event_listener.tag.class%">
-            <argument type="service" id="fos_http_cache.cache_manager" />
+            <argument type="service" id="fos_http_cache.handler.tag_handler" />
             <tag name="kernel.event_subscriber" />
         </service>
     </services>

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

@@ -35,25 +35,30 @@ Setting and Invalidating Tags
 You can tag responses in three ways: with the cache manager, configuration and
 annotations.
 
-Cache Manager
-~~~~~~~~~~~~~
+Tagging from code
+~~~~~~~~~~~~~~~~~
 
-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\Handler\TagHandler;
 
     class NewsController
     {
+        /**
+         * @var TagHandler
+         */
+        private $tagHandler;
+
         public function articleAction($id)
         {
-            $response = new Response('Some news article');
-            $this->cacheManager->tagResponse($response, array('news', 'news-' . $id));
+            $this->tagHandler->addTags(array('news', 'news-' . $id));
 
-            return $response;
+            // ...
         }
     }
 
-Then call ``invalidateTags($tags)`` to invalidate the tags you set::
+To invalidate tags, call ``TagHandler::invalidateTags($tags)``::
 
     class NewsController
     {
@@ -63,13 +68,13 @@ Then call ``invalidateTags($tags)`` to invalidate the tags you set::
         {
             // ...
 
-            $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,25 +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);
-
-``invalidateTags()``
---------------------
-
-Invalidate cache tags::
-
-    $cacheManager->invalidateTags(array('some-tag', 'other-tag'));
+.. versionadded:: 1.3
+    Since version 1.3, use the :doc:`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'));

Resources/doc/spelling_word_list.txt

@@ -7,3 +7,4 @@ symfony
 github
 subdomains
 yaml
+invalidator