Merge pull request #366 from FriendsOfSymfony/adjust-tag-header-configuration

Adjust to tag header cleanup and allow more configuration on varnish proxy client

Author: dbu

CHANGELOG.md

@@ -43,6 +43,13 @@ Changelog
   CacheManager::invalidateTags (if you use annotations for tag invalidation, you 
   don't need to change anything). Recording tags and writing them into the 
   responses is now done through the SymfonyResponseTagger.
+  The service `fos_http_cache.handler.tag_handler` no longer exists. For
+  tagging responses, use `fos_http_cache.http.symfony_response_tagger` instead,
+  and to invalidate tags use the service `fos_http_cache.cache_manager`.
+* **BC break:** The configuration `tags.header` has been removed. Configuring
+  the header for tagging responses is now done at `tags.response_header`.
+  Configuring the header for tag invalidation requests is now done at
+  `proxy_client.varnish.tags_header`.
 
 ### Tests
 

Resources/doc/features/tagging.rst

@@ -34,56 +34,71 @@ For more information, see :doc:`/reference/configuration/tags`.
 Setting and Invalidating Tags
 -----------------------------
 
-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.
+You can tag responses in different ways:
+
+* From PHP code by using the response tagger to set tags and the cache manager
+  to invalidate tags;
+* Set tags from twig templates with a function;
+* In project configuration or using annotations on controller actions.
+
+You can add tags before the response object exists. The tags are automatically
+added to the response by a listener. The listener also detects pending tag
+invalidations and flushes them. As with other invalidation operations, tag
+invalidation requests are flushed to the caching proxy
+:ref:`after the response has been sent <flushing>`.
 
 Tagging from Code
 ~~~~~~~~~~~~~~~~~
 
-Inject the ``TagHandler`` (service ``fos_http_cache.handler.tag_handler``) and
-use ``addTags($tags)`` to add tags that will be set on the response::
+To add tags to responses, inject the ``ResponseTagger`` (service
+``fos_http_cache.http.symfony_response_tagger``) and use ``addTags($tags)`` to
+add tags that will be set on the response::
 
-    use FOS\HttpCacheBundle\Handler\TagHandler;
+    use FOS\HttpCacheBundle\Http\SymfonyResponseTagger;
 
     class NewsController
     {
         /**
-         * @var TagHandler
+         * @var SymfonyResponseTagger
          */
-        private $tagHandler;
+        private $responseTagger;
 
         public function articleAction($id)
         {
-            $this->tagHandler->addTags(array('news', 'news-' . $id));
+            $this->responseTagger->addTags(array('news', 'news-' . $id));
 
             // ...
         }
     }
 
-To invalidate tags, call ``TagHandler::invalidateTags($tags)``::
+To invalidate tags, inject the ``CacheManager`` (service ``fos_http_cache.cache_manager``)
+and call ``invalidateTags($tags)`` on it::
+
+    use FOS\HttpCacheBundle\CacheManager;
 
     class NewsController
     {
-        // ...
+        /**
+         * @var CacheManager
+         */
+        private $cacheManager;
 
         public function editAction($id)
         {
             // ...
 
-            $this->tagHandler->invalidateTags(array('news-' . $id));
+            $this->cacheManager->invalidateTags(array('news-' . $id));
 
             // ...
         }
     }
 
-See the :ref:`Tag Handler reference <tag_handler_addtags>` for full details.
-
 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:
+with the response tagger and can also be mixed with the other methods:
 
 .. code-block:: jinja
 

Resources/doc/reference.rst

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

Resources/doc/reference/cache-manager.rst

@@ -1,8 +1,8 @@
 The Cache Manager
 =================
 
-Use the CacheManager to explicitly invalidate or refresh paths, URLs, routes or
-headers.
+Use the CacheManager to explicitly invalidate or refresh paths, URLs, routes,
+tags or responses with specific headers.
 
 By *invalidating* a piece of content, you tell your caching proxy to no longer
 serve it to clients. When next requested, the proxy will fetch a fresh copy
@@ -82,12 +82,16 @@ Refresh a Route::
 
 .. _cache_manager_tags:
 
-``tagResponse()``, ``invalidateTags()``
----------------------------------------
+``invalidateTags()``
+--------------------
+
+Invalidate cache tags::
+
+    $cacheManager->invalidateTags(array('some-tag', 'other-tag'));
+
+.. note::
 
-.. versionadded:: 1.3
-    Since version 1.3, use the :doc:`TagHandler <tag-handler>` instead of the
-    CacheManager for working with tags.
+    Marking a response with tags can be done through the :doc:`ResponseTagger <../features/tagging>`.
 
 .. _flushing:
 

Resources/doc/reference/configuration/proxy-client.rst

@@ -27,14 +27,42 @@ varnish
     fos_http_cache:
         proxy_client:
             varnish:
+                tags_header: My-Cache-Tags
+                header_length: 1234
+                default_ban_headers:
+                    Foo: Bar
                 http:
                     servers:
                         - 123.123.123.1:6060
                         - 123.123.123.2
                     base_url: yourwebsite.com
 
-``servers``
-"""""""""""
+``tags_header``
+"""""""""""""""
+
+**type**: ``string`` **default**: ``X-Cache-Tags``
+
+Header for sending tag invalidation requests to Varnish.
+
+``header_length``
+"""""""""""""""""
+
+**type**: ``integer`` **default**: ``7500``
+
+Maximum header length when invalidating tags. If there are more tags to
+invalidate than fit into the header, the invalidation request is split into
+multiple requests.
+
+``default_ban_headers``
+"""""""""""""""""""""""
+
+**type**: ``array``
+
+Map of header name header value that have to be set on each ban request. This
+list is merged with the built-in headers for bans.
+
+``http.servers``
+""""""""""""""""
 
 **type**: ``array``
 
@@ -46,8 +74,8 @@ When using a multi-server setup, make sure to include **all** proxy servers in
 this list. Invalidation must happen on all systems or you will end up with
 inconsistent caches.
 
-``base_url``
-""""""""""""
+``http.base_url``
+"""""""""""""""""
 
 **type**: ``string``
 

Resources/doc/reference/tag-handler.rst

@@ -8,6 +8,7 @@ symfony
 github
 subdomains
 yaml
+invalidations
 invalidator
 ETag
 templating

Resources/doc/spelling_word_list.txt

@@ -22,7 +22,7 @@
     ],
     "require": {
         "php": "^5.6.0||^7.0.0",
-        "friendsofsymfony/http-cache": "^2.0.0-beta1",
+        "friendsofsymfony/http-cache": "2.0.x-dev as 2.0.0-beta3",
         "symfony/framework-bundle": "^2.8||^3.0",
         "symfony/http-foundation": "~2.8.13||^3.1.6"
     },

composer.json

@@ -13,7 +13,6 @@
 
 use FOS\HttpCache\CacheInvalidator;
 use FOS\HttpCache\ProxyClient\ProxyClient;
-use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
 
 /**

src/CacheManager.php

@@ -11,6 +11,8 @@
 
 namespace FOS\HttpCacheBundle\DependencyInjection;
 
+use FOS\HttpCache\ProxyClient\Varnish;
+use FOS\HttpCache\TagHeaderFormatter\TagHeaderFormatter;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
 use Symfony\Component\Config\Definition\Builder\NodeBuilder;
 use Symfony\Component\Config\Definition\Builder\NodeDefinition;
@@ -307,8 +309,30 @@ private function addProxyClientSection(ArrayNodeDefinition $rootNode)
                             ->info('If you configure more than one proxy client, you need to specify which client is the default.')
                         ->end()
                         ->arrayNode('varnish')
+                            ->fixXmlConfig('default_ban_header')
+                            ->validate()
+                                ->always(function ($v) {
+                                    if (!count($v['default_ban_headers'])) {
+                                        unset($v['default_ban_headers']);
+                                    }
+
+                                    return $v;
+                                })
+                            ->end()
                             ->children()
-                                    ->append($this->getHttpDispatcherNode())
+                                ->scalarNode('tags_header')
+                                    ->defaultValue(Varnish::DEFAULT_HTTP_HEADER_CACHE_TAGS)
+                                    ->info('HTTP header to use when sending tag invalidation requests to Varnish')
+                                ->end()
+                                ->scalarNode('header_length')
+                                    ->info('Maximum header length when invalidating tags. If there are more tags to invalidate than fit into the header, the invalidation request is split into several requests.')
+                                ->end()
+                                ->arrayNode('default_ban_headers')
+                                    ->useAttributeAsKey('name')
+                                    ->info('Map of additional headers to include in each ban request.')
+                                    ->prototype('scalar')->end()
+                                ->end()
+                                ->append($this->getHttpDispatcherNode())
                             ->end()
                         ->end()
 
@@ -473,8 +497,8 @@ private function addTagSection(ArrayNodeDefinition $rootNode)
                             ->defaultNull()
                             ->info('Service name of a custom ExpressionLanugage to use.')
                         ->end()
-                        ->scalarNode('header')
-                            ->defaultValue('X-Cache-Tags')
+                        ->scalarNode('response_header')
+                            ->defaultValue(TagHeaderFormatter::DEFAULT_HEADER_NAME)
                             ->info('HTTP header that contains cache tags')
                         ->end()
                         ->arrayNode('rules')