Adding support for tagging from twig

Author: dbu

CHANGELOG.md

@@ -4,14 +4,16 @@ 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.
+* Configured/annotated cache tags on subrequests (in 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, and from
+  twig with the `fos_httpcache_tag` function.
+  
   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)
 * Added support for a simple Etag header in the header configuration (#207)
 

Resources/config/tag_listener.xml

@@ -14,6 +14,11 @@
             <argument>%fos_http_cache.tag_handler.header%</argument>
         </service>
 
+        <service id="fos_http_cache.twig.tag_extension" class="FOS\HttpCacheBundle\Twig\CacheTagExtension">
+            <argument id="fos_http_cache.handler.tag_handler" type="service"/>
+            <tag name="twig.extension"/>
+        </service>
+
         <service id="fos_http_cache.event_listener.tag"
                  class="%fos_http_cache.event_listener.tag.class%">
             <argument type="service" id="fos_http_cache.handler.tag_handler" />

Resources/doc/features/tagging.rst

@@ -32,10 +32,10 @@ For more information, see :doc:`/reference/configuration/tags`.
 Setting and Invalidating Tags
 -----------------------------
 
-You can tag responses in three ways: with the cache manager, configuration and
-annotations.
+You can tag responses in different ways: with the tag handler from PHP or with
+a twig function, from configuration or using annotations on controller actions.
 
-Tagging from code
+Tagging from Code
 ~~~~~~~~~~~~~~~~~
 
 Inject the ``TagHandler`` (service ``fos_http_cache.handler.tag_handler``) and
@@ -76,8 +76,31 @@ To invalidate tags, call ``TagHandler::invalidateTags($tags)``::
 
 See the :ref:`Tag Handler reference <tag_handler_addtags>` for full details.
 
-Configuration
-~~~~~~~~~~~~~
+Tagging from Twig Templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In situations where a page is assembled in the templating layer, it can be more
+convenient to add tags from inside the template. This works the same way as
+with the tag handler and can also be mixed with the other methods:
+
+.. code-block:: jinja
+
+    {# template.html.twig #}
+    {{ fos_httpcache_tag('mytag') }}
+    {{ fos_httpcache_tag(['tag-one', 'tag-two']) }}
+
+.. hint::
+
+    This twig function never outputs anything into the template but is only
+    called for the side effect of adding the tag to the response header.
+
+.. note::
+
+    Tag invalidation from twig would be a strange architecture and is therefore
+    not supported.
+
+Tagging with Configuration Rules
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Alternatively, you can :doc:`configure rules </reference/configuration/tags>`
 for setting and invalidating tags:
@@ -97,8 +120,8 @@ Now if a :term:`safe` request matches the criteria under ``match``, the response
 will be tagged with ``news``. When an unsafe request matches, the tag ``news``
 will be invalidated.
 
-Annotations
-~~~~~~~~~~~
+Tagging with Controller Annotations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Add the ``@Tag`` annotations to your controllers to set and invalidate tags::
 

Resources/doc/spelling_word_list.txt

@@ -9,3 +9,4 @@ subdomains
 yaml
 invalidator
 ETag
+templating

Tests/Functional/EventListener/TagSubscriberTest.php

@@ -95,6 +95,15 @@ public function testManualTagging()
         $this->assertEquals('manual-tag,sub-tag,sub-items,manual-items', $response->headers->get('X-Cache-Tags'));
     }
 
+    public function testTwigExtension()
+    {
+        $client = static::createClient();
+
+        $client->request('GET', '/tag_twig');
+        $response = $client->getResponse();
+        $this->assertEquals('tag-from-twig', $response->headers->get('X-Cache-Tags'));
+    }
+
     protected function tearDown()
     {
         static::createClient()->getContainer()->unmock('fos_http_cache.cache_manager');

Tests/Functional/Fixtures/Controller/TagController.php

@@ -66,4 +66,9 @@ public function subrequestAction()
 
         return new Response('subrequest');
     }
+
+    public function twigAction()
+    {
+        $this->render('::tag.html.twig');
+    }
 }

Tests/Functional/Fixtures/app/Resources/views/tag.html.twig

@@ -0,0 +1 @@
+{{ fos_httpcache_tag('tag-from-twig') }}

Tests/Functional/Fixtures/app/config/routing.yml

@@ -16,6 +16,10 @@ tag_manual:
   path: /tag_manual
   defaults: { _controller: FOS\HttpCacheBundle\Tests\Functional\Fixtures\Controller\TagController::manualAction }
 
+tag_twig:
+  path: /tag_twig
+  defaults: { _controller: FOS\HttpCacheBundle\Tests\Functional\Fixtures\Controller\TagController::twigAction }
+
 invalidation_route:
   path: /invalidate/route/{id}
   defaults: { _controller: FOS\HttpCacheBundle\Tests\Functional\Fixtures\Controller\InvalidationController::itemAction }

Tests/Unit/DependencyInjection/Compiler/HashGeneratorPassTest.php

@@ -43,7 +43,7 @@ public function testConfigNoContext()
         $config = $this->getBaseConfig();
         $this->extension->load(array($config), $container);
         $this->userContextListenerPass->process($container);
-        $this->assertCount(13, $container->getDefinitions());
+        $this->assertCount(14, $container->getDefinitions());
     }
 
     /**

Twig/CacheTagExtension.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace FOS\HttpCacheBundle\Twig;
+
+use FOS\HttpCache\Handler\TagHandler;
+
+/**
+ * A Twig extension to allow adding cache tags from twig templates.
+ */
+class CacheTagExtension extends \Twig_Extension
+{
+    /**
+     * @var TagHandler
+     */
+    private $tagHandler;
+
+    public function __construct(TagHandler $tagHandler)
+    {
+        $this->tagHandler = $tagHandler;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getFunctions()
+    {
+        return array(
+            new \Twig_SimpleFunction('fos_httpcache_tag', array($this, 'addTag')),
+        );
+    }
+
+    /**
+     * Add a single tag or an array of tags to the response.
+     *
+     * The tag string is *not* further processed, you can't use a comma
+     * separated string to pass several tags but need to build a twig array.
+     *
+     * Calling this twig function adds nothing to the output.
+     *
+     * @param string|array $tag
+     */
+    public function addTag($tag)
+    {
+        $this->tagHandler->addTags((array) $tag);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getName()
+    {
+        return 'fos_httpcache_tag_extension';
+    }
+}