added documentation and various cleanup

Author: dbu

doc/includes/custom-ttl.rst

@@ -0,0 +1,17 @@
+By default, the caching proxy looks at the ``s-maxage`` instruction in the
+``Cache-Control`` header to know for how long it should cache a page. But the
+``Cache-Control`` header is also sent to the client. Any caches on the Internet,
+for example the Internet provider or from a cooperate network might look at
+``s-maxage`` and cache the page. This can be a problem, notably when you do
+:doc:`explicit cache invalidation </cache-invalidator>`. In that
+scenario, you want your caching proxy to keep a page in cache for a long time,
+but caches outside your control must not keep the page for a long duration.
+
+One option could be to set a high ``s-maxage`` for the proxy and simply rewrite
+the response to remove or reduce the ``s-maxage``. This is not a good solution
+however, as you start to duplicate your caching rule definitions.
+
+The solution to this issue provided here is to use a separate, different header
+called ``X-Reverse-Proxy-TTL`` that controls the TTL of the caching proxy to
+keep ``s-maxage`` for other proxies. Because this is not a standard feature,
+you need to add configuration to your caching proxy.

doc/symfony-cache-configuration.rst

@@ -43,7 +43,10 @@ the cache. Instead, overwrite the constructor of AppCache and register the
 subscribers there. A simple cache will look like this::
 
     use FOS\HttpCache\SymfonyCache\EventDispatchingHttpCache;
+    use FOS\HttpCache\SymfonyCache\PurgeSubscriber;
+    use FOS\HttpCache\SymfonyCache\RefreshSubscriber;
     use FOS\HttpCache\SymfonyCache\UserContextSubscriber;
+    use FOS\HttpCache\SymfonyCache\CustomTtlListener();
 
     class AppCache extends EventDispatchingHttpCache
     {
@@ -54,9 +57,10 @@ subscribers there. A simple cache will look like this::
         {
             parent::__construct($kernel, $cacheDir);
 
-            $this->addSubscriber(new UserContextSubscriber());
             $this->addSubscriber(new PurgeSubscriber());
             $this->addSubscriber(new RefreshSubscriber());
+            $this->addSubscriber(new UserContextSubscriber());
+            $this->addSubscriber(new CustomTtlListener());
         }
     }
 
@@ -179,4 +183,17 @@ the ``session_name_prefix`` option) in the requests to the backend. If you need
 a different behavior, overwrite ``UserContextSubscriber::cleanupHashLookupRequest``
 with your own logic.
 
+Custom TTL
+~~~~~~~~~~
+
+.. include:: includes/custom-ttl.rst
+
+The ``CustomTtlSubscriber`` looks at a specific header to determine the TTL,
+preferring that over ``s-maxage``. The default header is ``X-Reverse-Proxy-TTL``
+but you can customize that in the subscriber constructor::
+
+    new CustomTtlSubscriber('My-TTL-Header');
+
+The custom header is removed before sending the response to the client.
+
 .. _HttpCache: http://symfony.com/doc/current/book/http_cache.html#symfony-reverse-proxy

doc/testing-your-application.rst

@@ -98,8 +98,10 @@ Make sure ``symfony/process`` is available in your project:
 
     $ composer require symfony/process
 
-Then set your Varnish configuration (VCL) file. All available configuration
-parameters are shown below.
+Then set your Varnish configuration (VCL) file. Configuration is handled either
+by overwriting the getter or by defining a PHP constant. You can set the
+constants in your ``phpunit.xml`` or in the bootstrap file. Available
+configuration parameters are:
 
 ======================= ========================= ================================================== ===========================================
 Constant                Getter                    Default                                            Description
@@ -109,10 +111,22 @@ Constant                Getter                    Default
 ``VARNISH_PORT``        ``getCachingProxyPort()`` ``6181``                                           port Varnish listens on
 ``VARNISH_MGMT_PORT``   ``getVarnishMgmtPort()``  ``6182``                                           Varnish management port
 ``VARNISH_CACHE_DIR``   ``getCacheDir()``         ``sys_get_temp_dir()`` + ``/foshttpcache-varnish`` directory to use for cache
-``VARNISH_VERSION``     ``getVarnishVersion()``   ``4``                                              installed varnish application version
 ``WEB_SERVER_HOSTNAME`` ``getHostName()``                                                            hostname your application can be reached at
 ======================= ========================= ================================================== ===========================================
 
+The Varnish version is controlled by an environment variable (in case you want
+to test both Varnish 3 and 4 on a continuous integration system). See the
+``.travis.yml`` of the FOSHttpCache git repository for an example.
+
+==================== ========================= ======= ===========================================
+Environment Variable Getter                    Default Description
+==================== ========================= ======= ===========================================
+``VARNISH_VERSION``  ``getVarnishVersion()``   ``4``   version of varnish application that is used
+==================== ========================= ======= ===========================================
+
+See ``tests/bootstrap.php`` for an example how this repository uses the version
+information to set the right ``VARNISH_FILE`` constant.
+
 Enable Assertions
 '''''''''''''''''