From 969182933dc56bb9ff944beac6bb7a834717e0c5 Mon Sep 17 00:00:00 2001
From: David de Boer <david@ddeboer.nl>
Date: Mon, 24 Feb 2014 22:39:11 +0100
Subject: [PATCH 1/3] Improve docs

Remove whitelines
---
 README.md                                 |   7 +-
 doc/cache-invalidator.md                  | 109 +++++++++-------------
 doc/{http-proxy.md => caching-proxy.md}   |   3 +
 doc/index.md                              |  35 ++++---
 doc/installation.md                       |  86 +++++++++--------
 doc/invalidation-introduction.md          |  41 ++++++++
 doc/varnish.md                            |  43 ++++-----
 tests/Functional/Fixtures/varnish/ban.vcl |   3 +-
 8 files changed, 181 insertions(+), 146 deletions(-)
 rename doc/{http-proxy.md => caching-proxy.md} (92%)
 create mode 100644 doc/invalidation-introduction.md

diff --git a/README.md b/README.md
index a5b44dbb..c7d3ab8d 100644
--- a/README.md
+++ b/README.md
@@ -12,9 +12,10 @@ This library integrates your PHP applications with HTTP caching proxies such as
 Use this library to send invalidation requests from your application to the caching proxy
 and to test your caching and invalidation code against a Varnish setup.
 
-If you use Symfony2, you want to look at the [FOSHttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle)
-which provides the invalidator as a service to Symfony2, along with a couple of
-other useful Symfony2 specific features to help with caching and caching proxies.
+If you use Symfony2, have a look at the
+[FOSHttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle).
+The bundle provides the invalidator as a service, along with a number of
+Symfony2-specific features to help with caching and caching proxies.
 
 Features
 --------
diff --git a/doc/cache-invalidator.md b/doc/cache-invalidator.md
index 82c2b19b..ffbb6af5 100644
--- a/doc/cache-invalidator.md
+++ b/doc/cache-invalidator.md
@@ -1,32 +1,21 @@
 The Cache Invalidator
-=================
+=====================
 
-Use the CacheInvalidator to explicitly invalidate or refresh paths, URLs or
+Use the cache invalidator to explicitly invalidate or refresh paths, URLs or
 headers.
 
-* [Setup](#setup)
-* [Invalidating paths and URLs](#invalidating-paths-and-urls)
-* [Refreshing paths and URLs](#refreshing-paths-and-urls)
+* [Invalidating Paths and URLs](#invalidating-paths-and-urls)
+* [Refreshing Paths and URLs](#refreshing-paths-and-urls)
 * [Invalidating with a Regular Expression](#invalidating-with-a-regular-expression)
+  * [URL, Content Type and Hostname](#urls-content-type-and-hostname)
+  * [Any Header](#any-header)
 * [Tags](#tags)
+  * [Changing the Tags Header](#changing-the-tags-header)
 * [Flushing](#flushing)
 * [Error handling](#error-handling)
+  * [Logging errors](#logging-errors)
 
-Setup
------
-
-The CacheInvalidator wraps a low-level caching proxy client. To construct the
-invalidator, pass the proxy client to it. For instance, when using [Varnish](varnish.md):
-
-```php
-use FOS\HttpCache\Invalidation\Varnish;
-use FOS\HttpCache\CacheInvalidator;
-
-$varnish = new Varnish(...);
-$cacheInvalidator = new CacheInvalidator($varnish);
-```
-
-Invalidating paths and URLs
+Invalidating Paths and URLs
 ---------------------------
 
 Make sure to configure your proxy for purging first.
@@ -35,15 +24,19 @@ Make sure to configure your proxy for purging first.
 Invalidate a path:
 
 ```php
-$cacheInvalidator->invalidatePath('/users');
+$cacheInvalidator->invalidatePath('/users')
+    ->flush()
+;
 ```
 
+See below for the `[flush()](#flushing)` method.
+
 Invalidate an URL:
 ```php
 $cacheInvalidator->invalidatePath('http://www.example.com/users');
 ```
 
-Refreshing paths and URLs
+Refreshing Paths and URLs
 -------------------------
 
 Make sure to configure your proxy for refreshing first.
@@ -61,24 +54,26 @@ Refresh an URL:
 $cacheInvalidator->refreshPath('http://www.example.com/users');
 ```
 
-Invalidating a path with a Regular Expression
----------------------------------------------
+Invalidating With a Regular Expression
+--------------------------------------
 
 Make sure to configure your proxy for regular expressions first.
 (See [varnish ban](varnish.md#ban).)
 
+### URL, Content Type and Hostname
+
 You can invalidate all URLs matching a regular expression by using the
 `invalidateRegex` method. You can further limit the cache entries to invalidate
-with a regular expression for the content type and/or the host name.
+with a regular expression for the content type and/or the hostname.
 
-For instance, to invalidate all .css files for all host names handled by this
+For instance, to invalidate all .css files for all hostnames handled by this
 caching proxy:
 
 ```php
 $cacheInvalidator->invalidateRegex('.*css$');
 ```
 
-To invalidate all png files for host example.com:
+To invalidate all .png files for host example.com:
 
 ```php
 $cacheInvalidator->invalidateRegex('.*', 'image/png', array('example.com'));
@@ -87,8 +82,7 @@ $cacheInvalidator->invalidateRegex('.*', 'image/png', array('example.com'));
 If you need other criteria than path, content type and hosts, use the
 `invalidate` method.
 
-Invalidating requests with any headers
---------------------------------------
+### Any Header
 
 You can also invalidate the cache based on any headers. If you use non-default
 headers, make sure to configure your proxy accordingly to have them taken into
@@ -103,38 +97,22 @@ To invalidate on a custom header X-My-Header, you would do:
 $cacheInvalidator->invalidate(array('X-My-Header' => 'my-value'));
 ```
 
-Fluent interface
-----------------
-
-The cache invalidator offers a fluent interface:
-
-```php
-$cacheInvalidator
-    ->invalidatePath('/bad/guys')
-    ->invalidatePath('/good/guys')
-    ->refreshPath('/')
-;
-```
-
 Tags
 ----
 
 Make sure to [configure your proxy for tagging](varnish.md#tagging) first.
-The examples in this section assume you left the `tagsHeader` unchanged. You
-can call `CacheInvalidator::setTagsHeader` to change the HTTP header used to
-identify tags.
 
 You will have to make sure your web application adds the correct tags on all
-responses. The [HttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle)
-provides means to help you with this, but without Symfony there is no generic
-way to do this.
+responses by setting the `X-Cache-Tags` header. The
+[FOSHttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle)
+does this for you when you’re using Symfony.
 
-Assume you sent 3 responses:
+Assume you sent four responses:
 
-* /one had the header `X-Cache-Tags: tag-one`
-* /two had the header `X-Cache-Tags: tag-two, group-a`
-* /three had the header `X-Cache-Tags: tag-three, group-a`
-* /four had the header `X-Cache-Tags: tag-four, group-b`
+* `/one` had the header `X-Cache-Tags: tag-one`
+* `/two` had the header `X-Cache-Tags: tag-two, group-a`
+* `/three` had the header `X-Cache-Tags: tag-three, group-a`
+* `/four` had the header `X-Cache-Tags: tag-four, group-b`
 
 You can now invalidate some URLs using tags:
 
@@ -142,10 +120,16 @@ You can now invalidate some URLs using tags:
 $cacheInvalidator->invalidateTags(array('group-a', 'tag-four'));
 ```
 
-This will ban all requests having either the tag group-a OR tag-four. In the
-above example, this will invalidate "/two", "/three" and "/four". Only "/one"
+This will ban all requests having either the tag `group-a` /or/ `tag-four`. In
+the above example, this will invalidate "/two", "/three" and "/four". Only "/one"
 will stay in the cache.
 
+### Changing The Tags Header
+
+Tagging uses a custom HTTP header to identify tags. You can change the default
+header `X-Cache-Tags` by calling `setTagsHeader()`. Make sure to reflect this
+change in your [caching proxy configuration](varnish.md#tagging).
+
 Flushing
 --------
 
@@ -160,16 +144,13 @@ $cacheInvalidator
 ;
 ```
 
-Note: When using the Symfony Bundle, the cache invalidator is automatically
-flushed. When using the Bundle, you only need to manually call flush when not
-in a request context. (E.g. from a command.)
-
-To keep the performance impact of sending invalidation requests to a minimum,
-make sure to only flush /after/ the response has been sent to the client’s
-browser.
+Try delaying flush until after the response has been sent to the client’s
+browser. This keeps the performance impact of sending invalidation requests to
+a minimum.
 
-The Varnish client also sends all invalidation requests in parallel to further
-reduce the time used by invalidation.
+When using the [Symfony bundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle),
+you don’t have to call `flush()`, as the bundle flushes the invalidator for you
+after the response has been sent.
 
 Error handling
 --------------
diff --git a/doc/http-proxy.md b/doc/caching-proxy.md
similarity index 92%
rename from doc/http-proxy.md
rename to doc/caching-proxy.md
index d5d70963..8bc296fb 100644
--- a/doc/http-proxy.md
+++ b/doc/caching-proxy.md
@@ -8,6 +8,9 @@ HTTP proxy.
 As with the CacheInvalidator, you need to call `flush()` to actually send requests
 to the backend.
 
+The CacheInvalidator is configured with an instance of CacheProxyInterface which
+also implements at least one of PurgeInterface, RefreshInterface, BanInterface.
+
 * [Purge](#purge)
 * [Ban](#ban)
 * [Refresh](#refresh)
diff --git a/doc/index.md b/doc/index.md
index 25255045..d4069749 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -1,20 +1,27 @@
-FOSHttpCache
-============
+FOSHttpCache Documentation
+==========================
 
-This is the documentation for the FOSHttpCache library. This library provides
-a client to let applications do cache invalidation. It provides implementations
-to talk to popular caching proxies.
+This is the documentation for the FOSHttpCache library.
 
-If you are a Symfony user, have a look at the [FOSHttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle)
-which integrates this library and provides a lot off additional features.
+This library integrates your PHP applications with HTTP caching proxies such as
+Varnish. Use this library to send invalidation requests from your application
+to the caching proxy and to test your caching and invalidation code against a
+Varnish setup.
+
+If you use Symfony2, have a look at the
+[FOSHttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle).
+The bundle provides the invalidator as a service, along with a number of
+Symfony2-specific features to help with caching and caching proxies.
 
 This documentation covers:
 
-1. [Installation and Getting Started](installation.md) of the library
-2. [Cache Invalidator](cache-invalidator.md)
-   1. [HTTP proxy](http-proxy.md), the low level details
-3. HTTP proxy configuration
-   1. [Varnish](varnish.md)
+1. [Installation and Getting Started](installation.md)
+2. [An Introduction to Cache Invalidation](invalidation-introduction.md)
+2. [The Cache Invalidator](cache-invalidator.md)
+3. [Caching Proxy Clients](caching-proxy.md)
+   1. [Interfaces](interfaces.md)
+   2. [Varnish Configuration](varnish-configuration.md)
+   3. [Nginx](nginx.md)
 4. Testing
-   1. Testing [your application](testing-your-application.md)’s caching and invalidation behaviour
-   2. Running [this library](testing-the-library.md)’s tests.
\ No newline at end of file
+   1. [Testing Your Application](testing-your-application.md)
+   2. [Testing the Library](testing-the-library.md)
\ No newline at end of file
diff --git a/doc/installation.md b/doc/installation.md
index 8b15f26f..4cb7ac3b 100644
--- a/doc/installation.md
+++ b/doc/installation.md
@@ -2,66 +2,72 @@ Installation
 ============
 
 This library is available on [Packagist](https://packagist.org/packages/friendsofsymfony/http-cache).
-You can install it using Composer:
+You can install it using [Composer](https://getcomposer.org/):
 
 ```bash
-$ composer require friendsofsymfony/http-cache:@stable
+$ composer require friendsofsymfony/http-cache:~1.0
 ```
 
 Getting Started
 ===============
 
-This library mainly provides the CacheInvalidator class. Use this class to collect
-cache invalidation requests in your application and call the `flush` method at
-the end of requests to have it send the invalidation requests to your server.
+There are three things you need to do to get started:
+1. [configure your caching proxy](#configure-your-caching-proxy)
+2. [construct a caching proxy client](#cosntruct-a-caching-proxy-client)
+3. [construct the cache invalidator](#construct-the-cache-invalidator).
 
-Cache Invalidation
-------------------
+Configure Your Caching Proxy
+----------------------------
 
-Basically, there are 3 operations:
+You should configure your [caching proxy](caching-proxy.md) to handle
+invalidation requests.
 
-* Purge: Invalidate a specific URL in all its variants (as specified by the
-  VARY header) and with all query strings. In the case of Varnish, this will
-  remove the entries from the cache immediately.
-* Refresh: Similar to purge: Invalidate a specific URL with all query strings,
-  but not its variants. Do an immediate request to the backend to have the page
-  in the cache again.
-* Ban: This is a way more powerful operation. Remove all requests matching
-  specified regular expressions on any desired headers. This can invalidate a
-  subset of URLs but also custom headers, as used with the
-  CacheInvalidator::invalidateTags method. In the case of Varnish, this will only
-  record the fact that cache entries are to be ignored, for performance
-  reasons.
+Currently, this library only supports Varnish. See the [Varnish](varnish.md)
+chapter for configuration instructions.
 
-All of these methods are explained in detail in the
-[Invalidation](invalidation.md) chapter.
+Construct a Caching Proxy Client
+--------------------------------
 
-Bootstrap
----------
+You now need to construct a client that communicates with your caching proxy
+server. The caching proxy client is an instance of
+[CacheProxyInterface](../src/Invalidation/CacheProxyInterface.php).
 
-The CacheInvalidator is configured with an instance of CacheProxyInterface which
-also implements at least one of PurgeInterface, RefreshInterface, BanInterface.
-Using the provided Varnish client, the bootstrap code looks as follows:
+Currently, this library offers one implementation: Varnish.
 
+At minimum, supply an array containing IPs or hostnames of the Varnish
+proxy servers that you want to send invalidation requests to:
 
 ```php
-use FOS\HttpCache\CacheInvalidator;
 use FOS\HttpCache\Invalidation\Varnish;
 
-// IPs varnish is listening on
-$ips = array('10.0.0.1:6081', '10.0.0.2:6081');
-// hostname to use in requests
-$host = 'www.test.com';
-$varnish = new Varnish(array $ips, $host);
+$servers = array('10.0.0.1:6081', '10.0.0.2:6081');
+$varnish = new Varnish($servers);
+```
+
+This is sufficient for invalidating absolute URLs. If you also wish to
+invalidate relative paths, supply the hostname (or base URL) where your website
+is available as the second parameter:
+
+```php
+$varnish = new Varnish($servers, 'my-cool-app.com');
+```
 
-// to get log messages if invalidation fails unexpectedly, give the client a
-// logger instance
-$varnish->setLogger(...);
+Construct the Cache Invalidator
+-------------------------------
+
+It is the [cache invalidator](cache-invalidator.md) that you will probably use
+most. Create it by passing the proxy client as an
+[adapter](http://en.wikipedia.org/wiki/Adapter_pattern):
+
+```php
+use FOS\HttpCache\CacheInvalidator;
 
 $cacheInvalidator = new CacheInvalidator($varnish);
 ```
 
-Thats it, you are ready to start caching. Read on in the next chapter about the
-[Cache Invalidator](cache-invalidator.md). You may also want to know more about the
-[Lower-level HTTP proxy classes](http-proxy.md) like the `Varnish` class we
-used in this example.
+You are now ready to start invalidating content.
+
+* If you are new to cache invalidation, you may want to read
+  [An Introduction to Cache Invalidation](invalidation-introduction.md) first.
+* Continue with the [Cache Invalidator](cache-invaldidator.md) to learn
+  how to send invalidation requests.
\ No newline at end of file
diff --git a/doc/invalidation-introduction.md b/doc/invalidation-introduction.md
new file mode 100644
index 00000000..35a5a542
--- /dev/null
+++ b/doc/invalidation-introduction.md
@@ -0,0 +1,41 @@
+An Introduction to Cache Invalidation
+=====================================
+
+This general introduction explains cache invalidation concepts. If you are
+already familiar with cache invalidation, you may wish to skip this chapter
+and continue to the [Cache Invalidator](cache-invalidator.md).
+
+What is Cache Invalidation?
+---------------------------
+
+Cache invalidation, also known as cache purging, ...
+
+Cache Invalidation Methods
+--------------------------
+
+There are three methods to invalidate content.
+
+### Purge
+
+**Purge** invalidates a specific URL in all its variants (as specified by the
+VARY header) and with all query strings. In the case of Varnish, this will
+remove the entries from the cache immediately.
+
+### Refresh
+
+**Refresh** is similar to purge: invalidates a specific URL with all query strings,
+but not its variants. Do an immediate request to the backend to have the page
+in the cache again.
+
+### Ban
+
+**Ban** is a way more powerful operation. Remove all requests matching
+specified regular expressions on any desired headers. This can invalidate a
+subset of URLs but also custom headers, as used with the
+CacheInvalidator::invalidateTags method. In the case of Varnish, this will only
+record the fact that cache entries are to be ignored, for performance
+reasons.
+
+Now, start invalidating content with:
+* the [Cache Invalidator](cache-invalidator.md)
+* or the low-level [Caching Proxy Clients](caching-proxy.md).
\ No newline at end of file
diff --git a/doc/varnish.md b/doc/varnish.md
index 2e6ce4dc..3626f323 100644
--- a/doc/varnish.md
+++ b/doc/varnish.md
@@ -1,10 +1,10 @@
-Varnish
-=======
+Varnish Configuration
+=====================
 
 This chapter describes how to configure Varnish to work with the library.
 
 * [Introduction](#introduction)
-* [Basic Varnish configuration](#basic-varnish-configuration)
+* [Basic Varnish Configuration](#basic-varnish-configuration)
 * [Purge](#purge)
 * [Refresh](#refresh)
 * [Ban](#ban)
@@ -13,18 +13,13 @@ This chapter describes how to configure Varnish to work with the library.
 Introduction
 ------------
 
-The [Varnish reverse caching proxy](https://www.varnish-cache.org) is a good
-choice for a caching proxy. This document is not meant to be an introduction to
-Varnish, so if you are not familiar with it, you might want to read some
-tutorial first.
-
 Below, you will find detailed Varnish configuration recommendations for the
 features provided by this library. The examples are tested with Varnish
 version 3.0. For a quick overview, you can also look at [the configuration
 that is used for the library’s functional tests]
 (../tests/Tests/Functional/Fixtures/varnish/fos.vcl).
 
-Basic Varnish configuration
+Basic Varnish Configuration
 ---------------------------
 
 To invalidate cached objects in Varnish, begin by adding an
@@ -80,6 +75,20 @@ sub vcl_miss {
 }
 ```
 
+Refresh
+-------
+
+If you want to invalidate cached objects by [forcing a refresh](https://www.varnish-cache.org/trac/wiki/VCLExampleEnableForceRefresh),
+add the following to your Varnish configuration:
+
+```varnish
+sub vcl_recv {
+    if (req.http.Cache-Control ~ "no-cache" && client.ip ~ invalidators) {
+        set req.hash_always_miss = true;
+    }
+}
+```
+
 Ban
 ---
 
@@ -115,24 +124,12 @@ sub vcl_deliver {
 }
 ```
 
-Refresh
--------
-
-If you want to invalidate cached objects by [forcing a refresh](https://www.varnish-cache.org/trac/wiki/VCLExampleEnableForceRefresh),
-add the following to your Varnish configuration:
-
-```varnish
-sub vcl_recv {
-    if (req.http.Cache-Control ~ "no-cache" && client.ip ~ invalidators) {
-        set req.hash_always_miss = true;
-    }
-}
-```
-
 Tagging
 -------
 
 Add the following to your Varnish configuration to enable [cache tagging](cache-invalidator.md#tags).
+The custom `X-Cache-Tags` header should match the tagging header
+[configured in the cache invalidator](cache-invalidator.md#changing-the-tags-header).
 
 ```varnish
 sub vcl_recv {
diff --git a/tests/Functional/Fixtures/varnish/ban.vcl b/tests/Functional/Fixtures/varnish/ban.vcl
index 95583d44..73274e97 100644
--- a/tests/Functional/Fixtures/varnish/ban.vcl
+++ b/tests/Functional/Fixtures/varnish/ban.vcl
@@ -26,12 +26,11 @@ sub vcl_fetch {
 
     # Set ban-lurker friendly custom headers
     set beresp.http.x-url = req.url;
-
-
     set beresp.http.x-host = req.http.host;
 }
 
 sub vcl_deliver {
+
     # Add extra headers if debugging is enabled
     if (!resp.http.x-cache-debug) {
         # Remove ban-lurker friendly custom headers when delivering to client

From e6f4611330a9682c85b707367ad70b9f3f0039dc Mon Sep 17 00:00:00 2001
From: David de Boer <david@ddeboer.nl>
Date: Sun, 2 Mar 2014 16:43:40 +0100
Subject: [PATCH 2/3] Update testing docs to reflect changes in library

Add HHVM compatibility as feature

Update TOC

Split Varnish into client and config

Improve docs on proxy client

Clean up Installation chapter

Add flush() to examples so users won't forget to call it

Add proxy config chapter

Finish general introduction

Fix links to introduction

Fix missing ;

Fix grammar

Fix code block

Update cache-invalidator.md

Remove link to self

Fix link to Alternatives

Fix host regex

Add missing Composer install step

Add note on Varnish port

Improve overview

Improve introduction
---
 README.md                                    |   2 +-
 doc/cache-invalidator.md                     | 105 +++++++++----
 doc/caching-proxy.md                         |  87 -----------
 doc/index.md                                 |  17 ++-
 doc/installation.md                          |  83 ++++------
 doc/invalidation-introduction.md             | 152 ++++++++++++++++---
 doc/proxy-clients.md                         | 121 +++++++++++++++
 doc/proxy-configuration.md                   |  10 ++
 doc/testing-the-library.md                   |  33 ++--
 doc/testing-your-application.md              |  20 ++-
 doc/varnish-client.md                        | 103 +++++++++++++
 doc/{varnish.md => varnish-configuration.md} | 109 ++++++++-----
 12 files changed, 580 insertions(+), 262 deletions(-)
 delete mode 100644 doc/caching-proxy.md
 create mode 100644 doc/proxy-clients.md
 create mode 100644 doc/proxy-configuration.md
 create mode 100644 doc/varnish-client.md
 rename doc/{varnish.md => varnish-configuration.md} (57%)

diff --git a/README.md b/README.md
index c7d3ab8d..93e59473 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,6 @@ FOSHttpCache
 [![Scrutinizer Quality Score](https://scrutinizer-ci.com/g/ddeboer/FOSHttpCache/badges/quality-score.png?s=5b808e92306a54228a81378ec20a47bb5313a5c7)](https://scrutinizer-ci.com/g/ddeboer/FOSHttpCache/)
 [![Code Coverage](https://scrutinizer-ci.com/g/ddeboer/FOSHttpCache/badges/coverage.png?s=f9f57d6b28285f38782b38a08b1dbdb24901a764)](https://scrutinizer-ci.com/g/ddeboer/FOSHttpCache/)
 
-
 Introduction
 ------------
 
@@ -23,6 +22,7 @@ Features
 * Send [cache invalidation requests](doc/cache-invalidator.md) with minimal impact on performance.
 * Use the built-in support for [Varnish](doc/varnish.md) or easily implement your own caching proxy client.
 * [Test your application](doc/testing-your-application.md) against your Varnish setup.
+* This library is compatible with [HHVM](http://www.hhvm.com/blog/).
 
 Documentation
 -------------
diff --git a/doc/cache-invalidator.md b/doc/cache-invalidator.md
index ffbb6af5..021f1a4a 100644
--- a/doc/cache-invalidator.md
+++ b/doc/cache-invalidator.md
@@ -1,25 +1,43 @@
 The Cache Invalidator
 =====================
 
-Use the cache invalidator to explicitly invalidate or refresh paths, URLs or
-headers.
+Use the cache invalidator to invalidate or refresh paths, URLs and headers.
+It is the invalidator that you will probably use most when interacting with
+the library. 
 
+* [Setup](#setup)
 * [Invalidating Paths and URLs](#invalidating-paths-and-urls)
 * [Refreshing Paths and URLs](#refreshing-paths-and-urls)
 * [Invalidating with a Regular Expression](#invalidating-with-a-regular-expression)
   * [URL, Content Type and Hostname](#urls-content-type-and-hostname)
   * [Any Header](#any-header)
 * [Tags](#tags)
-  * [Changing the Tags Header](#changing-the-tags-header)
+  * [Custom Tags Header](#custom-tags-header)
 * [Flushing](#flushing)
 * [Error handling](#error-handling)
   * [Logging errors](#logging-errors)
 
+Setup
+-----
+
+Create the cache invalidator by passing a [proxy client](proxy-clients.md) as
+an [adapter](http://en.wikipedia.org/wiki/Adapter_pattern):
+
+```php
+use FOS\HttpCache\CacheInvalidator;
+use FOS\HttpCache\Invalidation;
+
+$client = new Invalidation\Varnish();
+// or
+$client = new Invalidation\Nginx();
+
+$cacheInvalidator = new CacheInvalidator($client);
+```
+
 Invalidating Paths and URLs
 ---------------------------
 
-Make sure to configure your proxy for purging first.
-(See [varnish](varnish.md#purge).)
+Make sure to [configure your proxy](proxy-configuration.md) for purging first.
 
 Invalidate a path:
 
@@ -29,64 +47,64 @@ $cacheInvalidator->invalidatePath('/users')
 ;
 ```
 
-See below for the `[flush()](#flushing)` method.
+See below for the [flush](#flushing) method.
+
+Invalidate a URL:
 
-Invalidate an URL:
 ```php
-$cacheInvalidator->invalidatePath('http://www.example.com/users');
+$cacheInvalidator->invalidatePath('http://www.example.com/users')->flush();
 ```
 
 Refreshing Paths and URLs
 -------------------------
 
-Make sure to configure your proxy for refreshing first.
-(See [varnish](varnish.md#refresh).)
+Make sure to [configure your proxy](proxy-configuration.md) for refreshing
+first.
 
 Refresh a path:
 
 ```php
-$cacheInvalidator->refreshPath('/users');
+$cacheInvalidator->refreshPath('/users')->flush();
 ```
 
-Refresh an URL:
+Refresh a URL:
 
 ```php
-$cacheInvalidator->refreshPath('http://www.example.com/users');
+$cacheInvalidator->refreshPath('http://www.example.com/users')->flush();
 ```
 
 Invalidating With a Regular Expression
 --------------------------------------
 
-Make sure to configure your proxy for regular expressions first.
-(See [varnish ban](varnish.md#ban).)
+Make sure to [configure your proxy](proxy-configuration.md) for banning first.
 
 ### URL, Content Type and Hostname
 
 You can invalidate all URLs matching a regular expression by using the
 `invalidateRegex` method. You can further limit the cache entries to invalidate
-with a regular expression for the content type and/or the hostname.
+with a regular expression for the content type and/or the application hostname.
 
 For instance, to invalidate all .css files for all hostnames handled by this
 caching proxy:
 
 ```php
-$cacheInvalidator->invalidateRegex('.*css$');
+$cacheInvalidator->invalidateRegex('.*css$')->flush();
 ```
 
 To invalidate all .png files for host example.com:
 
 ```php
-$cacheInvalidator->invalidateRegex('.*', 'image/png', array('example.com'));
+$cacheInvalidator
+    ->invalidateRegex('.*', 'image/png', array('example.com'))
+    ->flush()
+;
 ```
 
-If you need other criteria than path, content type and hosts, use the
-`invalidate` method.
-
 ### Any Header
 
 You can also invalidate the cache based on any headers. If you use non-default
-headers, make sure to configure your proxy accordingly to have them taken into
-account. (See [varnish ban](varnish.md#ban).)
+headers, make sure to [configure your proxy accordingly](proxy-configuration.md)
+to have them taken into account.
 
 Cache client implementations should fill up the headers to at least have the
 default headers always present to simplify the cache configuration rules.
@@ -94,13 +112,13 @@ default headers always present to simplify the cache configuration rules.
 To invalidate on a custom header X-My-Header, you would do:
 
 ```php
-$cacheInvalidator->invalidate(array('X-My-Header' => 'my-value'));
+$cacheInvalidator->invalidate(array('X-My-Header' => 'my-value'))->flush();
 ```
 
 Tags
 ----
 
-Make sure to [configure your proxy for tagging](varnish.md#tagging) first.
+Make sure to [configure your proxy for tagging](proxy-configuration.md) first.
 
 You will have to make sure your web application adds the correct tags on all
 responses by setting the `X-Cache-Tags` header. The
@@ -117,18 +135,18 @@ Assume you sent four responses:
 You can now invalidate some URLs using tags:
 
 ```php
-$cacheInvalidator->invalidateTags(array('group-a', 'tag-four'));
+$cacheInvalidator->invalidateTags(array('group-a', 'tag-four'))->flush();
 ```
 
 This will ban all requests having either the tag `group-a` /or/ `tag-four`. In
-the above example, this will invalidate "/two", "/three" and "/four". Only "/one"
+the above example, this will invalidate `/two`, `/three` and `/four`. Only `/one`
 will stay in the cache.
 
-### Changing The Tags Header
+### Custom Tags Header
 
 Tagging uses a custom HTTP header to identify tags. You can change the default
 header `X-Cache-Tags` by calling `setTagsHeader()`. Make sure to reflect this
-change in your [caching proxy configuration](varnish.md#tagging).
+change in your [caching proxy configuration](varnish-configuration.md#tagging).
 
 Flushing
 --------
@@ -165,6 +183,27 @@ These exception are of two types:
 * `\FOS\HttpCache\ProxyResponseException` when the caching proxy returns an
    error response, such as 403 Forbidden.
 
+So, to catch exceptions:
+
+```php
+use FOS\HttpCache\Exception\ExceptionCollection;
+
+$cacheInvalidator
+    ->invalidatePath('/users');
+
+try {
+    $cacheInvalidator->flush();
+} catch (ExceptionCollection $exceptions) {
+    // The first exception that occurred
+    var_dump($exceptions->getFirst());
+
+    // Iterate over the exception collection
+    foreach ($exceptions as $exception) {
+        var_dump($exception);
+    }
+}
+```
+
 ### Logging errors
 
 You can log any exceptions in the following way. First construct a logger that
@@ -174,8 +213,8 @@ implements `\Psr\Log\LoggerInterface`. For instance, when using
 ```php
 use Monolog\Logger;
 
-$logger = new Logger(...);
-$logger->pushHandler(...);
+$monolog = new Logger(...);
+$monolog->pushHandler(...);
 ```
 
 Then add the logger as a subscriber to the cache invalidator:
@@ -183,7 +222,7 @@ Then add the logger as a subscriber to the cache invalidator:
 ```php
 use FOS\HttpCache\EventListener\LogSubscriber;
 
-$subscriber = new LogSubscriber($logger);
+$subscriber = new LogSubscriber($monolog);
 $cacheInvalidator->addSubscriber($subscriber);
 ```
 
@@ -200,4 +239,4 @@ try {
 } catch (ExceptionCollection $exceptions) {
     // At least one failed request, check your logs!
 }
-```
\ No newline at end of file
+```
diff --git a/doc/caching-proxy.md b/doc/caching-proxy.md
deleted file mode 100644
index 8bc296fb..00000000
--- a/doc/caching-proxy.md
+++ /dev/null
@@ -1,87 +0,0 @@
-HTTP proxy
-==========
-
-Use the HTTP proxy classes (currently this library provides only a client for
-Varnish) for lower-level access to invalidation functionality offered by your
-HTTP proxy.
-
-As with the CacheInvalidator, you need to call `flush()` to actually send requests
-to the backend.
-
-The CacheInvalidator is configured with an instance of CacheProxyInterface which
-also implements at least one of PurgeInterface, RefreshInterface, BanInterface.
-
-* [Purge](#purge)
-* [Ban](#ban)
-* [Refresh](#refresh)
-
-Purge
------
-
-Make sure to [configure your proxy for purging](varnish.md#purge) first.
-
-```php
-$proxy
-    ->purge('/my/path')
-    ->purge('http://myapp.dev/absolute/url')
-;
-```
-
-Refresh
--------
-
-Make sure to [configure your proxy for refreshing](varnish.md#refresh) first.
-
-You can refresh a path or an absolute URL by calling the `refresh` method:
-
-```php
-$varnish
-    ->refresh('/my/path')
-    ->refresh('http://myapp.dev/absolute/url')
-;
-```
-
-Ban
----
-
-Make sure to [configure your proxy for banning](varnish.md#ban) first.
-
-The basic `ban` method just allows to send any headers you need to limit what
-content is being invalidated. There is a convenience method `banPath` that
-accepts a regular expression for the URL to invalidate, and an optional content
-type regular expression and a list of host names.
-
-You can invalidate all URLs matching a regular expression by using the
-`ban` method:
-
-For instance, to ban all .png files on all hosts:
-
-```php
-$varnish->banPath('.*png$');
-);
-```
-
-To ban all HTML URLs that begin with `/articles/`:
-
-```php
-$varnish->banPath('/articles/.*', 'text/html');
-```
-
-By default, URLs will be banned on all hosts. You can limit this by specifying
-a host header:
-
-```php
-$varnish->banPath('*.png$', null, 'example.com');
-```
-
-If you want to go beyond that, you can use the `ban` method directly:
-
-```php
-$varnish->ban(array(
-    Varnish::HTTP_HEADER_URL => '.*\.png$',
-    Varnish::HTTP_HEADER_HOST => '.*example\.com',
-    Varnish::HTTP_HEADER_CACHE => 'my-tag',
-));
-
-You can also add your own headers to the [varnish ban code](varnish.md#ban) if
-you need more.
diff --git a/doc/index.md b/doc/index.md
index d4069749..f6647800 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -13,15 +13,18 @@ If you use Symfony2, have a look at the
 The bundle provides the invalidator as a service, along with a number of
 Symfony2-specific features to help with caching and caching proxies.
 
-This documentation covers:
+Table of Contents
+-----------------
 
 1. [Installation and Getting Started](installation.md)
 2. [An Introduction to Cache Invalidation](invalidation-introduction.md)
-2. [The Cache Invalidator](cache-invalidator.md)
-3. [Caching Proxy Clients](caching-proxy.md)
-   1. [Interfaces](interfaces.md)
-   2. [Varnish Configuration](varnish-configuration.md)
-   3. [Nginx](nginx.md)
-4. Testing
+3. Caching Proxy Configuration
+   1. [Varnish Configuration](varnish-configuration.md)
+   2. Nginx Configuration
+4. [Caching Proxy Clients](proxy-clients.md)
+   1. [Varnish client](varnish-client.md)
+   2. Nginx client
+5. [The Cache Invalidator](cache-invalidator.md)
+6. Testing
    1. [Testing Your Application](testing-your-application.md)
    2. [Testing the Library](testing-the-library.md)
\ No newline at end of file
diff --git a/doc/installation.md b/doc/installation.md
index 4cb7ac3b..284a2aa3 100644
--- a/doc/installation.md
+++ b/doc/installation.md
@@ -1,73 +1,44 @@
+Getting started
+===============
+
 Installation
-============
+------------
 
-This library is available on [Packagist](https://packagist.org/packages/friendsofsymfony/http-cache).
+The FOSHttpCache library is available on [Packagist](https://packagist.org/packages/friendsofsymfony/http-cache).
 You can install it using [Composer](https://getcomposer.org/):
 
 ```bash
 $ composer require friendsofsymfony/http-cache:~1.0
 ```
 
-Getting Started
-===============
+Configuration
+-------------
 
 There are three things you need to do to get started:
-1. [configure your caching proxy](#configure-your-caching-proxy)
-2. [construct a caching proxy client](#cosntruct-a-caching-proxy-client)
-3. [construct the cache invalidator](#construct-the-cache-invalidator).
-
-Configure Your Caching Proxy
-----------------------------
-
-You should configure your [caching proxy](caching-proxy.md) to handle
-invalidation requests.
-
-Currently, this library only supports Varnish. See the [Varnish](varnish.md)
-chapter for configuration instructions.
-
-Construct a Caching Proxy Client
---------------------------------
-
-You now need to construct a client that communicates with your caching proxy
-server. The caching proxy client is an instance of
-[CacheProxyInterface](../src/Invalidation/CacheProxyInterface.php).
-
-Currently, this library offers one implementation: Varnish.
+1. [configure your caching proxy](proxy-configuration.md)
+2. [set up a client for your caching proxy](proxy-clients.md)
+3. [set up the cache invalidator](cache-invalidator).
 
-At minimum, supply an array containing IPs or hostnames of the Varnish
-proxy servers that you want to send invalidation requests to:
+Overview
+--------
 
-```php
-use FOS\HttpCache\Invalidation\Varnish;
+This library mainly consists of:
+* low-level clients for communicating with caching proxies (Varnish and Nginx)
+* a cache invalidator that acts as an abstraction layer for the caching proxy
+  clients
+* test classes that you can use for integration testing your application
+  against a caching proxy.
 
-$servers = array('10.0.0.1:6081', '10.0.0.2:6081');
-$varnish = new Varnish($servers);
-```
-
-This is sufficient for invalidating absolute URLs. If you also wish to
-invalidate relative paths, supply the hostname (or base URL) where your website
-is available as the second parameter:
-
-```php
-$varnish = new Varnish($servers, 'my-cool-app.com');
-```
-
-Construct the Cache Invalidator
--------------------------------
-
-It is the [cache invalidator](cache-invalidator.md) that you will probably use
-most. Create it by passing the proxy client as an
-[adapter](http://en.wikipedia.org/wiki/Adapter_pattern):
-
-```php
-use FOS\HttpCache\CacheInvalidator;
-
-$cacheInvalidator = new CacheInvalidator($varnish);
-```
+Measures have been taken to minimise the performance impact of sending
+invalidation requests:
+* Requests are not sent immediately, but aggregated to be sent in parallel.
+* You can determine when the requests should be sent. For optimal performance,
+  do so after the response has been sent to the client.
 
-You are now ready to start invalidating content.
+Continue Reading
+----------------
 
 * If you are new to cache invalidation, you may want to read
   [An Introduction to Cache Invalidation](invalidation-introduction.md) first.
-* Continue with the [Cache Invalidator](cache-invaldidator.md) to learn
-  how to send invalidation requests.
\ No newline at end of file
+* Continue with the [Proxy Configuration](proxy-configuration.md) chapter to
+  learn how to configure your caching proxy to work with this library.
\ No newline at end of file
diff --git a/doc/invalidation-introduction.md b/doc/invalidation-introduction.md
index 35a5a542..2d41d032 100644
--- a/doc/invalidation-introduction.md
+++ b/doc/invalidation-introduction.md
@@ -5,37 +5,155 @@ This general introduction explains cache invalidation concepts. If you are
 already familiar with cache invalidation, you may wish to skip this chapter
 and continue to the [Cache Invalidator](cache-invalidator.md).
 
+* [HTTP Caching Terminology](#http-caching-terminology)
+* [What is Cache Invalidation?](#what-is-cache-invalidation)
+  * [The Problem](#the-problem)
+  * [Alternatives](#alternatives)
+  * [Disadvantages](#disadvantages)
+* [Invalidation Methods](#invalidation-methods)
+  * [Purge](#purge)
+  * [Refresh](#refresh)
+  * [Ban](#ban)
+
+HTTP Caching Terminology
+------------------------
+
+<dl>
+    <dt>Client</dt>
+    <dd>
+        The client that requests web representations of the application data.
+        This client can be visitor of a website, or for instance a client that
+        fetches data from a REST API.
+    </dd>
+    <dt>Application</dt>
+    <dd>
+        Also *backend application* or *origin server*. The web application that
+        holds the data.
+    </dd>
+    <dt>Caching proxy</dt>
+    <dd>
+        Also [reverse caching proxy](http://en.wikipedia.org/wiki/Reverse_proxy).
+        Examples: Varnish, Nginx.
+    </dd>
+    <dt>Time to live (TTL)</dt>
+    <dd>
+        Maximum lifetime of some content. Expressed in either an expiry date
+        for the content (the `Expires:` header) or its maximum age (the
+        `max-age` and `s-maxage` cache control directives).
+    </dd>
+</dl>
+
 What is Cache Invalidation?
 ---------------------------
 
-Cache invalidation, also known as cache purging, ...
+> There are only two hard things in Computer Science: cache invalidation and
+> naming things.
+>
+> — *Phil Karlton*
+
+### The problem
+
+HTTP caching is a great solution for improving the performance of your web
+application. For lower load on the application and fastest response time, you
+want to cache content for a long period. But at the same time, you want your
+clients see fresh content as soon as there was an update.
+
+Instead of finding some compromise, you can have both with cache invalidation.
+When application data changes, the application takes care of invalidating its
+web representation as out-of-date. Although caching proxies may handle
+invalidation differently, the effect is always the same: the next time a client
+requests the data, he or she gets a new version instead of the outdated one.
+
+### Alternatives
+
+There are three alternatives to cache invalidation.
+
+1. The first is to *expire* your cached content quickly by reducing its time to
+   live (TTL). However, short TTLs cause a higher load on the application
+   because content must be fetched from it more often. Moreover, reduced TTL
+   does not guarantee that clients will have fresh content, especially if the
+   content changes very rapidly as a result of client interactions with the
+   application.
+
+2. The second alternative is to *validate* the freshness of cached content at
+   every request. Again, this means more load on your application, even if you
+   return early (for instance by using HEAD requests).
 
-Cache Invalidation Methods
---------------------------
+3. The last resort is to *not cache* volatile content at all. While this
+   guarantees the user always sees changes without delay, it obviously
+   increases your application load even more.
 
-There are three methods to invalidate content.
+Cache invalidation gives you the best of both worlds: you can have very long
+TTLs, so when content changes little, it can be served from the cache because
+no requests to your application are required. At the same time, when data
+does change, that change is reflected without delay in the web representations.
+
+### Disadvantages
+
+Cache invalidation has two possible downsides:
+
+* Invalidating cached web representations when their underlying data changes
+  can be very simple. For instance, invalidate `/articles/123` when article 123
+  is updated. However, data usually is represented not in one but in multiple
+  representations. Article 123 could also be represented on the articles index
+  (`/articles`), the list of articles in the current year (`/articles/current`)
+  and in search results (`/search?name=123`). In this case, when article 123 is
+  changed, a lot more is involved in invalidating all of its representations.
+  In other words, invalidation adds a layer of complexity to your application.
+  This library tries to help reduce complexity, for instance by
+  [tagging](#tags) cached content. Additionally, if you use Symfony2, we
+  recommend you use the [FOSHttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle),
+  which provides additional functionality to make invalidation easier.
+* Invalidation is done through requests to your caching proxy. Sending these
+  requests could negatively influence performance, in particular if the client
+  has to wait for them. This library resolves this issue by optimizing the way
+  invalidation requests are sent.
+
+Invalidation Methods
+--------------------
+
+Cached content can be invalidated in three ways. Some caching proxies, such as
+Varnish, support all three methods. Others, such as Nginx, support purge and
+refresh only.
 
 ### Purge
 
-**Purge** invalidates a specific URL in all its variants (as specified by the
-VARY header) and with all query strings. In the case of Varnish, this will
-remove the entries from the cache immediately.
+Purge removes content from the caching proxy immediately. The next time a
+client requests the URL, data is fetched from the application, stored in
+the caching proxy, and returned to the client.
+
+Purge removes a specific URL in all its variants (as specified by the `Vary`
+header) and with all its query strings.
 
 ### Refresh
 
-**Refresh** is similar to purge: invalidates a specific URL with all query strings,
-but not its variants. Do an immediate request to the backend to have the page
-in the cache again.
+Just like purge, refresh removes cached content immediately. Additionally, the
+new content is fetched from the backend application. The next time a client
+requests the URL, no roundtrip to the application is necessary, as the new data
+is already available in the cache.
+
+Refresh invalidates a specific URL with all query string, but *not* its variants.
 
 ### Ban
 
-**Ban** is a way more powerful operation. Remove all requests matching
-specified regular expressions on any desired headers. This can invalidate a
-subset of URLs but also custom headers, as used with the
-CacheInvalidator::invalidateTags method. In the case of Varnish, this will only
-record the fact that cache entries are to be ignored, for performance
-reasons.
+Unlike purge and refresh, ban does not remove the content from the cache
+immediately. Instead, a reference to the content is added to a blacklist (or
+ban list). Every client request is checked against this blacklist. If the
+request happens to match blacklisted content, fresh content is fetched from the
+application, stored in the caching proxy and returned to the client.
+
+Bans cannot remove content from cache immediately because that would require
+going through all cached content, which could take a long time and reduce
+performance of the cache. Varnish contains a
+[ban lurker](https://www.varnish-software.com/blog/ban-lurker) that crawls the
+content to eventually throw out banned data even when it’s not requested by any
+client.
+
+The ban solution may seem cumbersome, but offers more powerful cache
+invalidation, such as selecting content to be banned by regular expressions.
+This opens the way for powerful invalidation schemes, such as tagging cache
+entries.
 
 Now, start invalidating content with:
 * the [Cache Invalidator](cache-invalidator.md)
-* or the low-level [Caching Proxy Clients](caching-proxy.md).
\ No newline at end of file
+* or the low-level [Caching Proxy Clients](proxy-clients.md).
diff --git a/doc/proxy-clients.md b/doc/proxy-clients.md
new file mode 100644
index 00000000..e928cc63
--- /dev/null
+++ b/doc/proxy-clients.md
@@ -0,0 +1,121 @@
+Caching Proxy Clients
+=====================
+
+You can use the caching proxy clients either wrapped by the cache invalidator
+(recommended), or directly for low-level access to invalidation functionality.
+
+You should set up at least one caching proxy client:
+
+* [Varnish client](varnish-client.md)
+* [Nginx client](nginx-client.md)
+
+Continue reading here for general information about the interfaces that are
+implemented by the clients.
+
+* [CacheProxyInterface](#cacheproxyinterface)
+* [PurgeInterface](#purgeinterface)
+* [RefreshInterface](#refreshinterface)
+* [BanInterface](#baninterface)
+
+CacheProxyInterface
+-------------------
+
+Each client is an implementation of [CacheProxyInterface](../src/Invalidation/CacheProxyInterface.php).
+All other interfaces, `PurgeInterface`, `RefreshInterface` and `BanInterface`
+extend this `CacheProxyInterface`. So each client implements at least one of
+the three [invalidation methods](invalidation-introduction.md#invalidation-methods),
+depending on the caching proxy’s abilities.
+
+The `CacheProxyInterface` has one method: `flush()`. After collecting
+invalidation requests, `flush()` needs to be called to actually send the
+requests to the caching proxy. This is on purpose: this way, we can send
+all requests together, reducing the performance impact of sending invalidation
+requests.
+
+PurgeInterface
+--------------
+
+If the caching proxy understands [purge requests](invalidation-introduction.md#purge),
+its client should implement `PurgeInterface`. Use the `purge($url)` method to
+purge one specific URL. The URL can be either an absolute URL or a relative
+path:
+
+```php
+$client
+    ->purge('http://my-app.com/some/path')
+    ->purge('/other/path')
+    ->flush()
+;
+```
+
+RefreshInterface
+----------------
+
+If the caching proxy understands [refresh requests](invalidation-introduction.md#refresh),
+its client should implement `RefreshInterface`. Use the
+`refresh($url, array $headers = array())` method to refresh one specific
+URL. The URL can be either an absolute URL or a relative path:
+
+```php
+$client
+    ->refresh('http://my-app.com/some/path')
+    ->refresh('other/path')
+    ->flush()
+;
+```
+
+You can also specify HTTP headers. For instance, to only refresh the JSON
+representation of an URL:
+
+```php
+$client
+    ->refresh('/some/path', array('Accept' => 'application/json')
+    ->flush()
+;
+```
+
+BanInterface
+------------
+
+If the caching proxy understands [ban requests](invalidation-introduction.md#ban),
+its client should implement `BanInterface`.
+
+You can invalidate all URLs matching a regular expression by using the
+`banPath($path, $contentType, $hosts)` method. It accepts a regular expression
+for the path to invalidate and an optional content type regular expression and
+list of application hostnames.
+
+For instance, to ban all .png files on all application hosts:
+
+```php
+$client->banPath('.*png$');
+```
+
+To ban all HTML URLs that begin with `/articles/`:
+
+```php
+$client->banPath('/articles/.*', 'text/html');
+```
+
+By default, URLs will be banned on all application hosts. You can limit this by
+specifying a host header:
+
+```php
+$client->banPath('*.png$', null, '^www.example.com$');
+```
+
+If you want to go beyond banning combinations of path, content type and hostname,
+use the `ban(array $headers)` method. This method allows you to specify any
+combination of headers that should be banned. For instance, when using the
+[Varnish client](varnish-client.md):
+
+```php
+$varnish->ban(array(
+    Varnish::HTTP_HEADER_URL   => '.*\.png$',
+    Varnish::HTTP_HEADER_HOST  => '.*example\.com',
+    Varnish::HTTP_HEADER_CACHE => 'my-tag',
+));
+```
+
+Make sure to add any headers that you want to ban on to your
+[caching proxy configuration](proxy-configuration.md).
diff --git a/doc/proxy-configuration.md b/doc/proxy-configuration.md
new file mode 100644
index 00000000..7356b63c
--- /dev/null
+++ b/doc/proxy-configuration.md
@@ -0,0 +1,10 @@
+Caching Proxy Configuration
+===========================
+
+To use this library, you need to configure your HTTP caching proxy to handle
+invalidation requests.
+
+This bundle currently supports the Varnish and Nginx caching proxies:
+
+* [Varnish configuration](varnish-configuration.md)
+* Nginx configuration
\ No newline at end of file
diff --git a/doc/testing-the-library.md b/doc/testing-the-library.md
index 3540417a..f3ab026d 100644
--- a/doc/testing-the-library.md
+++ b/doc/testing-the-library.md
@@ -1,26 +1,33 @@
-Testing the library
+Testing the Library
 ===================
 
 This chapter describes how to run the tests that are included with this library.
 
-Unit tests
+First clone the repository, install the vendors, then run the tests:
+
+```bash
+$ git clone https://github.com/FriendsOfSymfony/FOSHttpCache.git
+$ cd FOSHttpCache
+$ composer install --dev
+$ phpunit
+```
+
+Unit Tests
 ----------
 
-To run this library’s unit tests: clone the repository, install its vendors and
-invoice PHPUnit:
+To run the unit tests separately:
 
 ```bash
-$ git clone https://github.com/ddeboer/FOSHttpCache.git
-$ composer install --dev
-$ phpunit --testsuite unit
+$ phpunit tests/Unit
 ```
 
-Functional tests
+Functional Tests
 ----------------
 
 The library also includes functional tests against a Varnish instance. The
 functional test suite by default uses PHP’s built-in web server. If you have
-PHP 5.4 or newer, simply run with the default configuration.
+PHP 5.4 or newer or [HHVM](http://www.hhvm.com/), simply run with the default
+configuration.
 
 If you want to run the tests on PHP 5.3, you need to configure a web server
 listening on localhost:8080 that points to the folder
@@ -29,10 +36,8 @@ listening on localhost:8080 that points to the folder
 Run the functional tests:
 
 ```bash
-$ git clone https://github.com/ddeboer/FOSHttpCache.git
-$ composer install --dev
-$ phpunit --testsuite functional
+$ phpunit tests/Functional
 ```
 
-For more information about testing, see the [Testing your application](testing-your-application.md)
-chapter.
\ No newline at end of file
+For more information about testing, see the
+[Testing Your Application](testing-your-application.md) chapter.
\ No newline at end of file
diff --git a/doc/testing-your-application.md b/doc/testing-your-application.md
index bd464575..781e8396 100644
--- a/doc/testing-your-application.md
+++ b/doc/testing-your-application.md
@@ -1,13 +1,13 @@
-Testing your application
+Testing Your Application
 ========================
 
 This chapter describes how to test your application against a Varnish instance.
 
 * [VarnishTestCase](#varnishtestcase)
 * [Configuration](#configuration)
-  * [Setting constants](#setting-constants)
-  * [Overriding getters](#overriding-getters)
-  * [Enable assertions](#enable-assertions)
+  * [Setting Constants](#setting-constants)
+  * [Overriding Getters](#overriding-getters)
+  * [Enable Assertions](#enable-assertions)
 * [Usage](#usage)
 
 VarnishTestCase
@@ -35,16 +35,15 @@ All you have to do, is to refer the class to your Varnish configuration (VCL)
 file. The recommended way to configure the test case is by setting constants
 in your `phpunit.xml`. Alternatively, you can override the getter methods:
 
-
 | Constant             | Getter                 | Default    | Description                                 |
 | -------------------- | ---------------------- | ---------- | ------------------------------------------- |
 | `VARNISH_FILE`       | `getConfigFile()`      |            | your Varnish configuration (VCL) file       |
 | `VARNISH_BINARY`     | `getBinary()`          | `varnishd` | your Varnish binary                         |
-| `VARNISH_PORT`       | `getVarnishPort()`     | `6181`     | port Varnish listens on                     |
+| `VARNISH_PORT`       | `getCachingProxyPort()`| `6181`     | port Varnish listens on                     |
 | `VARNISH_MGMT_PORT`  | `getVarnishMgmtPort()` | `6182`     | Varnish management port                     |
 | `WEB_SERVER_HOSTNAME`| `getHostName()`        |            | hostname your application can be reached at |
 
-### Setting constants
+### Setting Constants
 
 Compare this library’s configuration to see how the constants are set:
 
@@ -59,7 +58,7 @@ Compare this library’s configuration to see how the constants are set:
 </phpunit>
 ```
 
-### Overriding getters
+### Overriding Getters
 
 You can override getters in your test class in the following way.
 
@@ -75,11 +74,10 @@ class YourFunctionalTest extends VarnishTestCase
 }
 ```
 
-### Enable assertions
+### Enable Assertions
 
 For the `assertHit` and `assertMiss` assertions to work, you should add a
-custom `X-Debug` header to responses served by your Varnish. See
-[this library’s VCL](../tests/FOS/HttpCache/Functional/Fixtures/Varnish/fos.vcl) for an example.
+[custom `X-Debug` header](varnish-configuration#debugging) to responses served by your Varnish.
 
 Usage
 -----
diff --git a/doc/varnish-client.md b/doc/varnish-client.md
new file mode 100644
index 00000000..e423b598
--- /dev/null
+++ b/doc/varnish-client.md
@@ -0,0 +1,103 @@
+Varnish Client
+==============
+
+The Varnish client supports all [cache invalidation methods](proxy-clients.md).
+
+* [Setup](#setup)
+* [Usage](#usage)
+  * [Purge](#purge)
+  * [Refresh](#refresh)
+  * [Ban](#ban)
+
+Setup
+-----
+
+At minimum, supply an array containing IPs or hostnames of the Varnish servers
+that you want to send invalidation requests to. Make sure to include the port
+Varnish runs on if it is not port 80.
+
+```php
+use FOS\HttpCache\Invalidation\Varnish;
+
+$servers = array('10.0.0.1', '10.0.0.2:6081'); // Port 80 assumed for 10.0.0.1
+$varnish = new Varnish($servers);
+```
+
+This is sufficient for invalidating absolute URLs. If you also wish to
+invalidate relative paths, supply the hostname (or base URL) where your website
+is available as the second parameter:
+
+```php
+$varnish = new Varnish($servers, 'my-cool-app.com');
+```
+
+Usage
+-----
+
+The Varnish clients supports all cache invalidation methods:
+* [purge](proxy-clients.md#purge)
+* [refresh](proxy-clients.md#refresh)
+* [ban](proxy-clients.md#ban).
+
+Make sure to [configure your Varnish servers](varnish-configuration.md) for
+each method that you wish to use.
+
+Purge
+-----
+
+Make sure to first [configure Varnish for purge](varnish-configuration.md#purge).
+
+```php
+$proxy
+    ->purge('/my/path')
+    ->purge('http://myapp.dev/absolute/url')
+    ->flush()
+;
+```
+
+Read more about [purging](proxy-clients.md#purgeinterface).
+
+Refresh
+-------
+
+Make sure to first [configure Varnish for refresh](varnish-configuration.md#refresh).
+
+```php
+$varnish
+    ->refresh('/my/path')
+    ->refresh('http://myapp.dev/absolute/url')
+    ->flush()
+;
+```
+
+Read more about [refreshing](proxy-clients.md#refreshinterface).
+
+Ban
+---
+
+Make sure to first [configure Varnish for ban](varnish-configuration.md#ban).
+
+```php
+$varnish->banPath('.*png$')
+    ->banPath('/articles/.*', 'text/html')
+    ->banPath('.*png$', null, 'example.com')
+    ->flush()
+;
+```
+
+To ban an array of header regular expressions:
+
+```php
+$varnish
+    ->ban(
+        array(
+            Varnish::HTTP_HEADER_URL => '.*\.png$',
+            Varnish::HTTP_HEADER_HOST => '.*example\.com',
+            Varnish::HTTP_HEADER_CACHE => 'my-tag',
+        )
+    )
+    ->flush()
+;
+```
+
+Read more about [banning](proxy-clients.md#baninterface).
\ No newline at end of file
diff --git a/doc/varnish.md b/doc/varnish-configuration.md
similarity index 57%
rename from doc/varnish.md
rename to doc/varnish-configuration.md
index 3626f323..e0169bd2 100644
--- a/doc/varnish.md
+++ b/doc/varnish-configuration.md
@@ -9,15 +9,16 @@ This chapter describes how to configure Varnish to work with the library.
 * [Refresh](#refresh)
 * [Ban](#ban)
 * [Tagging](#tagging)
+* [Debugging](#debugging)
 
 Introduction
 ------------
 
-Below, you will find detailed Varnish configuration recommendations for the
+Below you will find detailed Varnish configuration recommendations for the
 features provided by this library. The examples are tested with Varnish
 version 3.0. For a quick overview, you can also look at [the configuration
 that is used for the library’s functional tests]
-(../tests/Tests/Functional/Fixtures/varnish/fos.vcl).
+(../tests/Tests/Functional/Fixtures/varnish/).
 
 Basic Varnish Configuration
 ---------------------------
@@ -39,6 +40,8 @@ acl invalidators {
 }
 ```
 
+See also this library’s [basic configuration](../tests/Tests/Functional/Fixtures/varnish/fos.vcl).
+
 Warning: Make sure that all web servers running your application that may
 trigger invalidation are whitelisted here. Otherwise, lost cache invalidation
 requests will lead to lots of confusion.
@@ -52,29 +55,31 @@ To configure Varnish for [handling PURGE requests](https://www.varnish-cache.org
 # /etc/varnish/your_varnish.vcl
 
 sub vcl_recv {
-  if (req.request == "PURGE") {
-    if (!client.ip ~ invalidators) {
-      error 405 "PURGE not allowed";
+    if (req.request == "PURGE") {
+        if (!client.ip ~ invalidators) {
+          error 405 "PURGE not allowed";
+        }
+        return (lookup);
     }
-    return (lookup);
-  }
 }
 
 sub vcl_hit {
-  if (req.request == "PURGE") {
-    purge;
-    error 200 "Purged";
-  }
+    if (req.request == "PURGE") {
+        purge;
+        error 200 "Purged";
+    }
 }
 
 sub vcl_miss {
-  if (req.request == "PURGE") {
-    purge;
-    error 404 "Not in cache";
-  }
+    if (req.request == "PURGE") {
+        purge;
+        error 404 "Not in cache";
+    }
 }
 ```
 
+See also this library’s [purge.vcl](../tests/Tests/Functional/Fixtures/varnish/purge.vcl).
+
 Refresh
 -------
 
@@ -89,6 +94,8 @@ sub vcl_recv {
 }
 ```
 
+See also this library’s [refresh.vcl](../tests/Tests/Functional/Fixtures/varnish/refresh.vcl).
+
 Ban
 ---
 
@@ -98,52 +105,60 @@ To configure Varnish for [handling BAN requests](https://www.varnish-software.co
 # /etc/varnish/your_varnish.vcl
 
 sub vcl_recv {
-  if (req.request == "BAN") {
-      if (!client.ip ~ invalidators) {
-          error 405 "Not allowed.";
-      }
-      ban("obj.http.x-host ~ " + req.http.x-ban-host + " && obj.http.x-url ~ " + req.http.x-ban-url + " && obj.http.x-content-type ~ " + req.http.x-ban-content-type);
-      error 200 "Banned";
-  }
+    if (req.request == "BAN") {
+        if (!client.ip ~ invalidators) {
+            error 405 "Not allowed.";
+        }
+
+        ban("obj.http.x-host ~ " + req.http.x-ban-host
+            + " && obj.http.x-url ~ " + req.http.x-ban-url
+            + " && obj.http.x-content-type ~ " + req.http.x-ban-content-type
+        );
+
+        error 200 "Banned";
+    }
 }
 
-# Set BAN lurker friendly tags on object
 sub vcl_fetch {
-  set beresp.http.x-url = req.url;
-  set beresp.http.x-host = req.http.host;
-  set beresp.http.x-content-type = req.http.content-type;
+    # Set BAN lurker friendly tags on object
+    set beresp.http.x-url = req.url;
+    set beresp.http.x-host = req.http.host;
 }
 
-# Remove tags when delivering to client
 sub vcl_deliver {
-  if (! resp.http.X-Cache-Debug) {
-    unset resp.http.x-url;
-    unset resp.http.x-host;
-    unset resp.http.x-content-type;
-  }
+    # Remove tags when delivering to client
+    if (!resp.http.X-Cache-Debug) {
+        unset resp.http.x-url;
+        unset resp.http.x-host;
+    }
 }
 ```
 
+See also this library’s [ban.vcl](../tests/Tests/Functional/Fixtures/varnish/ban.vcl).
+
 Tagging
 -------
 
 Add the following to your Varnish configuration to enable [cache tagging](cache-invalidator.md#tags).
 The custom `X-Cache-Tags` header should match the tagging header
-[configured in the cache invalidator](cache-invalidator.md#changing-the-tags-header).
+[configured in the cache invalidator](cache-invalidator.md#custom-tags-header).
 
 ```varnish
 sub vcl_recv {
-    # ...
-
     if (req.request == "BAN") {
-        # ...
+        if (!client.ip ~ invalidators) {
+            error 405 "Not allowed.";
+        }
+
         if (req.http.x-cache-tags) {
+            # Banning tags
             ban("obj.http.host ~ " + req.http.x-host
                 + " && obj.http.x-url ~ " + req.http.x-url
                 + " && obj.http.content-type ~ " + req.http.x-content-type
                 + " && obj.http.x-cache-tags ~ " + req.http.x-cache-tags
             );
         } else {
+            # Not banning tags
             ban("obj.http.host ~ " + req.http.x-host
                 + " && obj.http.x-url ~ " + req.http.x-url
                 + " && obj.http.content-type ~ " + req.http.x-content-type
@@ -154,3 +169,25 @@ sub vcl_recv {
     }
 }
 ```
+
+See also this library’s [ban.vcl](../tests/Tests/Functional/Fixtures/varnish/ban.vcl).
+
+Debugging
+---------
+
+Configure your Varnish to set a debug header that shows whether a cache hit or miss occurred:
+
+```varnish
+sub vcl_deliver {
+    # Add extra headers if debugging is enabled
+    if (resp.http.x-cache-debug) {
+        if (obj.hits > 0) {
+            set resp.http.X-Cache = "HIT";
+        } else {
+            set resp.http.X-Cache = "MISS";
+        }
+    }
+}
+```
+
+See also this library’s [debug.vcl](../tests/Tests/Functional/Fixtures/varnish/debug.vcl).
\ No newline at end of file

From e2f4b53181c9e5e644b8e586777b78b8d76710dd Mon Sep 17 00:00:00 2001
From: David de Boer <david@ddeboer.nl>
Date: Tue, 4 Mar 2014 13:56:14 +0100
Subject: [PATCH 3/3] Clean up Varnish clients chapter

---
 doc/varnish-client.md | 76 +++++--------------------------------------
 1 file changed, 9 insertions(+), 67 deletions(-)

diff --git a/doc/varnish-client.md b/doc/varnish-client.md
index e423b598..eb5933d9 100644
--- a/doc/varnish-client.md
+++ b/doc/varnish-client.md
@@ -34,70 +34,12 @@ $varnish = new Varnish($servers, 'my-cool-app.com');
 Usage
 -----
 
-The Varnish clients supports all cache invalidation methods:
-* [purge](proxy-clients.md#purge)
-* [refresh](proxy-clients.md#refresh)
-* [ban](proxy-clients.md#ban).
-
-Make sure to [configure your Varnish servers](varnish-configuration.md) for
-each method that you wish to use.
-
-Purge
------
-
-Make sure to first [configure Varnish for purge](varnish-configuration.md#purge).
-
-```php
-$proxy
-    ->purge('/my/path')
-    ->purge('http://myapp.dev/absolute/url')
-    ->flush()
-;
-```
-
-Read more about [purging](proxy-clients.md#purgeinterface).
-
-Refresh
--------
-
-Make sure to first [configure Varnish for refresh](varnish-configuration.md#refresh).
-
-```php
-$varnish
-    ->refresh('/my/path')
-    ->refresh('http://myapp.dev/absolute/url')
-    ->flush()
-;
-```
-
-Read more about [refreshing](proxy-clients.md#refreshinterface).
-
-Ban
----
-
-Make sure to first [configure Varnish for ban](varnish-configuration.md#ban).
-
-```php
-$varnish->banPath('.*png$')
-    ->banPath('/articles/.*', 'text/html')
-    ->banPath('.*png$', null, 'example.com')
-    ->flush()
-;
-```
-
-To ban an array of header regular expressions:
-
-```php
-$varnish
-    ->ban(
-        array(
-            Varnish::HTTP_HEADER_URL => '.*\.png$',
-            Varnish::HTTP_HEADER_HOST => '.*example\.com',
-            Varnish::HTTP_HEADER_CACHE => 'my-tag',
-        )
-    )
-    ->flush()
-;
-```
-
-Read more about [banning](proxy-clients.md#baninterface).
\ No newline at end of file
+The Varnish client supports all cache invalidation methods:
+1. [purge](proxy-clients.md#purge); make sure to first [configure Varnish for purge](varnish-configuration.md#purge)
+2. [refresh](proxy-clients.md#refresh); make sure to first [configure Varnish for refresh](varnish-configuration.md#refresh)
+3. [ban](proxy-clients.md#ban); make sure to first [configure Varnish for ban](varnish-configuration.md#ban).
+
+* See the [Caching Proxy Clients](proxy-clients.md) chapter for more information
+  on how to use the invalidation methods.
+* See the [Varnish Configuration](varnish-configuration.md) chapter for more on
+  preparing your Varnish server for handling invalidation requests.
\ No newline at end of file