various tweaks and cleanups

DependencyInjection/Configuration.php

@@ -460,10 +460,6 @@ private function addFlashMessageSection(ArrayNodeDefinition $rootNode)
                             ->defaultFalse()
                             ->info('Whether the cookie should only be transmitted over a secure HTTPS connection from the client.')
                         ->end()
-                        ->scalarNode('httpOnly')
-                            ->defaultTrue()
-                            ->info('Whether the cookie will be made accessible only through the HTTP protocol.')
-                        ->end()
                     ->end()
                 ->end()
             ->end();

EventListener/FlashMessageSubscriber.php

@@ -98,7 +98,7 @@ public function onKernelResponse(FilterResponseEvent $event)
             $this->options['path'],
             $this->options['host'],
             $this->options['secure'],
-            $this->options['httpOnly']
+            false
         );
 
         $response->headers->setCookie($cookie);

Resources/doc/features.rst

@@ -1,8 +1,8 @@
 Features
 ========
 
-This part introduces the bundle’s features. Each feature links to the Reference
-chapter for a fuller explanation.
+This part introduces the bundle’s features. Each feature section links to the
+corresponding reference section.
 
 .. toctree::
 

Resources/doc/features/headers.rst

@@ -1,6 +1,8 @@
 Caching Headers
 ===============
 
+**Prerequisites**: *None*
+
 You can configure HTTP caching headers based on request and response properties.
 This configuration approach is more convenient than `manually setting cache headers`_
 and an alternative to `setting caching headers through annotations`_.

Resources/doc/features/helpers/flash-message.rst

@@ -1,6 +1,8 @@
 Flash Message Subscriber
 ========================
 
+**Prerequisites**: *None*
+
 When flash messages are rendered into the content of a page, you can't cache
 the page anymore. When enabled, this subscriber reads all flash messages into a
 cookie, leading to them not being there anymore when rendering the template.
@@ -17,11 +19,7 @@ the options under ``flash_message``.
     # app/config.yml
     fos_http_cache:
         flash_message:
-            name: flashes
-            path: /
-            host: null
-            secure: false
-            httpOnly: false
+            enabled: true
 
 On the client side, you need some JavaScript code that reads out the flash
 messages from the cookie and writes them into the DOM, then deletes the cookie

Resources/doc/features/invalidation.rst

@@ -1,6 +1,8 @@
 Invalidation
 ============
 
+**Prerequisites**: :ref:`Configure caching proxy <foshttpcache:proxy-configuration>`.
+
 By *invalidating* a piece of content, you tell your HTTP caching proxy (Varnish
 or Nginx) to no longer serve it to clients. When next requested, the proxy will
 fetch a fresh copy from the backend application and serve that instead. By

Resources/doc/features/tagging.rst

@@ -1,6 +1,8 @@
 Tagging
 =======
 
+**Prerequisites**: :ref:`Configure caching proxy for banning <foshttpcache:varnish-configuration#ban>` (only supported with Varnish).
+
 If your application has many intricate relationships between cached items,
 which makes it complex to invalidate them by route, cache tagging will be
 useful.

Resources/doc/features/user-context.rst

@@ -1,8 +1,10 @@
 User Context
 ============
 
+**Prerequisites**: :ref:`Configure caching proxy for user context <foshttpcache:varnish-configuration#user-context>` (only supported with Varnish).
+
 If your application serves different content depending on the user’s group
-or context (guest, editor, admin), you can can that content by user context.
+or context (guest, editor, admin), you can cache that content per user context.
 Each user context (group) gets its own unique hash, which is then used to vary
 content on. The event subscriber responds to hash requests and sets the Vary
 header. This way, you can differentiate your content between user groups while

Resources/doc/includes/enabled.rst

@@ -1,7 +1,7 @@
 enabled
 -------
 
-**type**: ``enum`` **default**: ``auto`` **options**: ``true``, ``false``, ``auto``
+**type**: ``enum``, **default**: ``auto``, **options**: ``true``, ``false``, ``auto``
 
 Enabled by default if :ref:`ExpressionLanguage is installed <expression language requirement>`
 and you have :doc:`configured a proxy client </reference/configuration/proxy-client>`.

Resources/doc/index.rst

@@ -5,9 +5,9 @@ This is the documentation for the `FOSHttpCacheBundle <https://github.com/Friend
 Use the FOSHttpCacheBundle to:
 
 * set HTTP caching headers in your application configuration based on request
-  properties such as path and controller
-* tag your response caches with annotations
-* invalidate cached paths, routes and tags with the FOSHttpCache_ library
+  properties such as path and controller;
+* tag your response caches with annotations;
+* invalidate cached paths, routes and tags with the FOSHttpCache_ library;
 * differentiate cached content per user type.
 
 Contents

Resources/doc/overview.rst

@@ -30,6 +30,8 @@ Then add the bundle to your application:
         );
     }
 
+For most features, you also need to :ref:`configure a caching proxy <foshttpcache:proxy-configuration>`.
+
 .. _requirements:
 
 Requirements
@@ -72,8 +74,12 @@ later, you need to explicitly add the component:
 
     $ composer require symfony/expression-language
 
-Now you can configure the bundle under the ``fos_http_cache`` key as explained
-in the :doc:`reference/configuration` section.
+Configuration
+-------------
+
+Now you can configure the bundle under the ``fos_http_cache`` key. The
+:doc:`features` section contains configuration examples, for
+a reference see the :doc:`reference/configuration` section.
 
 Functionality
 -------------

Resources/doc/reference/annotations.rst

@@ -6,7 +6,9 @@ actions are executed.
 
 .. note::
 
-    Make sure to :ref:`install the dependencies first <requirements>`.
+    Annotations need the SensioFrameworkExtraBundle. Some features also need
+    the ExpressionLanguage. Make sure to
+    :ref:`installed the dependencies first <requirements>`.
 
 .. _invalidatepath:
 

Resources/doc/reference/configuration/flash-message.rst

@@ -1,4 +1,54 @@
 Flash Message Configuration
 ===========================
 
-TODO
+The :doc:`flash message listener <../../features/helpers/flash-message>` is a
+tool to avoid rendering the flash message into the content of a page. It is
+another building brick for caching pages for logged in users.
+
+.. code-block:: yaml
+
+    # app/config.yml
+    fos_http_cache:
+        flash_message:
+            enabled: true
+            name: flashes
+            path: /
+            host: null
+            secure: false
+
+enabled
+-------
+
+**type**: ``boolean`` **default**: ``false``
+
+This event subscriber is disabled by default. You can set enabled to true if
+the default values for all options are good for you. When you configure any of
+the options, the subscriber is automatically enabled.
+
+name
+----
+
+**type**: ``string`` **default**: ``flashes``
+Set the name of the cookie.
+
+
+path
+----
+
+**type**: ``string`` **default**: ``/``
+
+The cookie path to use.
+
+host
+----
+
+**type**: ``string``
+
+Set the host for the cookie, e.g. to share among subdomains.
+
+secure
+------
+
+**type**: ``boolean`` **default**: ``false``
+
+Whether the cookie may only be passed through HTTPS.

Resources/doc/reference/configuration/headers.rst

@@ -3,7 +3,8 @@ cache_control
 
 The configuration contains a number of *rules*. When a request matches the
 parameters described in the ``match`` section, the headers as defined under
-``headers`` will be set on the response, if they are not already set.
+``headers`` will be set on the response, if they are not already set. Rules are
+checked in the order specified, where the first match wins.
 
 .. code-block:: yaml
 
@@ -16,7 +17,11 @@ parameters described in the ``match`` section, the headers as defined under
                     match:
                         host: ^login.example.com$
                     headers:
-                        cache_control: { public: false, max_age: 0, s_maxage: 0, last_modified: "-1 hour" }
+                        cache_control:
+                            public: false
+                            max_age: 0
+                            s_maxage: 0
+                            last_modified: "-1 hour"
                         vary: [Accept-Encoding, Accept-Language]
 
                 # match all actions of a specific controller
@@ -25,52 +30,43 @@ parameters described in the ``match`` section, the headers as defined under
                         attributes: { _controller: ^AcmeBundle:Default:.* }
                         additional_cacheable_status: [400]
                     headers:
-                        cache_control: { public: true, max_age: 15, s_maxage: 30, last_modified: "-1 hour" }
+                        cache_control:
+                            public: true
+                            max_age: 15
+                            s_maxage: 30
+                            last_modified: "-1 hour"
 
                 -
                     match:
                         path: ^/$
                     headers:
-                        cache_control: { public: true, max_age: 64000, s_maxage: 64000, last_modified: "-1 hour" }
+                        cache_control:
+                            public: true
+                            max_age: 64000
+                            s_maxage: 64000
+                            last_modified: "-1 hour"
                         vary: [Accept-Encoding, Accept-Language]
 
                 # match everything to set defaults
                 -
                     match:
                         path: ^/
                     headers:
-                        cache_control: { public: true, max_age: 15, s_maxage: 30, last_modified: "-1 hour" }
+                        cache_control:
+                            public: true
+                            max_age: 15
+                            s_maxage: 30
+                            last_modified: "-1 hour"
 
 rules
 -----
 
 **type**: ``array``
 
-A set of cache control rules.
+A set of cache control rules consisting of *match* criteria and *header* instructions.
 
 .. include:: /includes/match.rst
 
-.. sidebar:: Merging headers
-
-    If the response already has certain cache directives set, they are not
-    overwritten. The configuration can thus specify defaults that may be
-    changed by controllers or services that handle the response, or ``@Cache``
-    annotations.
-
-    The listener that applies the rules is triggered at priority 10, which
-    makes it handle before the ``@Cache`` annotations from the
-    SensioFrameworkExtraBundle are evaluated. Those annotations unconditionally
-    overwrite cache directives.
-
-    The only exception is responses that *only* have the ``no-cache``
-    directive. This is the default value for the cache control and there is no
-    way to determine if it was manually set. If the full header is only
-    ``no-cache``, the whole cache control is overwritten.
-
-    You can prevent the cache control on specific requests by injecting the
-    service ``fos_http_cache.event_listener.cache_control`` and calling
-    ``setSkip()`` on it. If this method is called, no cache rules are applied.
-
 headers
 ^^^^^^^
 
@@ -107,6 +103,25 @@ headers
 In the ``headers`` section, you define what headers to set on the response if
 the request was matched.
 
+Headers are **merged**. If the response already has certain cache directives
+set, they are not overwritten. The configuration can thus specify defaults
+that may be changed by controllers or services that handle the response, or
+``@Cache`` annotations.
+
+The listener that applies the rules is triggered at priority 10, which
+makes it handle before the ``@Cache`` annotations from the
+SensioFrameworkExtraBundle are evaluated. Those annotations unconditionally
+overwrite cache directives.
+
+The only exception is responses that *only* have the ``no-cache``
+directive. This is the default value for the cache control and there is no
+way to determine if it was manually set. If the full header is only
+``no-cache``, the whole cache control is overwritten.
+
+You can prevent the cache control on specific requests by injecting the
+service ``fos_http_cache.event_listener.cache_control`` and calling
+``setSkip()`` on it. If this method is called, no cache rules are applied.
+
 cache_control
 """""""""""""
 
@@ -227,7 +242,7 @@ reverse_proxy_ttl
 
 **type**: ``integer``
 
-For X-Reverse-Proxy-TTL for Custom Reverse Proxy Time-Outs
+Set a X-Reverse-Proxy-TTL header for reverse proxy time-outs not driven by ``s-maxage``.
 
 By default, reverse proxies use the ``s-maxage`` of your ``Cache-Control`` header
 to know how long it should cache a page. But by default, the s-maxage is also
@@ -255,7 +270,9 @@ then use on the reverse proxy:
                 -
                     headers:
                         reverse_proxy_ttl: 3600
-                        cache_control: { public: true, s_maxage: 60 }
+                        cache_control:
+                            public: true
+                            s_maxage: 60
 
 This example adds the header ``X-Reverse-Proxy-TTL: 3600`` to your responses.
 Varnish by default knows nothing about this header. To make this solution work,

Resources/doc/reference/configuration/invalidation.rst

@@ -28,7 +28,8 @@ rules
 **type**: ``array``
 
 A set of invalidation rules. Each rule consists of a match definition and
-one or more routes that will be invalidated. The routes are invalidated when:
+one or more routes that will be invalidated. Rules are checked in the order
+specified, where the first match wins. The routes are invalidated when:
 
 1. the HTTP request matches *all* criteria defined under ``match``
 2. the HTTP response is successful.

Resources/doc/reference/configuration/match.rst

@@ -1,14 +1,17 @@
+Matching
+========
+
+Several parts of the configuration use ``match`` sections to limit
+configuration to specific requests and responses. Matches are used for
+:doc:`caching headers <headers>`, :doc:`invalidation <invalidation>` and
+:doc:`tag rules <tags>`.
 match
-=====
+-----
 
 **type**: ``array``
 
-Defines the matching part of a :doc:`cache <headers>`, :doc:`invalidation <invalidation>`
-or :doc:`tag rule <tags>`. It contains one or more match criteria for
-requests. All criteria are regular expressions. They are checked in the order
-specified, where the first match wins.
-
-All matching criteria are regular expressions. For instance:
+A match contains one or more match criteria for requests. All matching criteria
+are regular expressions. For instance:
 
 .. code-block:: yaml
 

Resources/doc/reference/configuration/tags.rst

@@ -30,7 +30,8 @@ rules
 **type**: ``array``
 
 Write your tagging rules by combining a ``match`` definition with a ``tags``
-array. These tags will be set on the response when all of the following are true:
+array.  Rules are checked in the order specified, where the first match wins.
+These tags will be set on the response when all of the following are true:
 
 .. include:: /includes/safe.rst
 

Tests/Resources/Fixtures/config/full.php

@@ -100,7 +100,6 @@
         'path' => '/x',
         'host' => 'y',
         'secure' => true,
-        'httpOnly' => false,
     ),
     'debug' => array(
         'header' => 'FOS-Cache-Debug',