Add optional headers to purge call

doc/proxy-clients.rst

@@ -103,6 +103,21 @@ path::
         ->flush()
     ;
 
+You can specify HTTP headers as the second argument to ``purge()``.
+For instance::
+
+    $client
+        ->purge('/some/path', array('X-Foo' => 'bar')
+        ->flush()
+    ;
+
+Please note that purge will invalidate all variants, so you do not have to
+send any headers that you vary on, such as ``Accept``.
+
+The above allows you to pass headers that are different between purge requests.
+If you want to send headers for all purge requests, such as ``Authorization``,
+use a :ref:`custom Guzzle client <custom Guzzle client>` instead.
+
 Refresh
 ~~~~~~~
 
@@ -163,3 +178,23 @@ Varnish client::
 
 Make sure to add any headers that you want to ban on to your
 :doc:`Varnish configuration <varnish-configuration>`.
+
+.. _custom guzzle client:
+
+Custom Guzzle Client
+--------------------
+
+By default, the proxy clients instantiate a `Guzzle client`_ to communicate
+with the caching proxy. If you need to customize the requests, for example to
+send a basic authentication header, you can inject a custom Guzzle client::
+
+    use FOS\HttpCache\ProxyClient\Varnish;
+    use Guzzle\Http\Client;
+
+    $client = new Client();
+    $client->setDefaultOption('auth', array('username', 'password', 'Digest'));
+
+    $servers = array('10.0.0.1');
+    $varnish = new Varnish($servers, '/baseUrl', $client);
+
+.. _Guzzle client: http://guzzle3.readthedocs.org/

src/ProxyClient/Invalidation/PurgeInterface.php

@@ -30,9 +30,11 @@ interface PurgeInterface extends ProxyClientInterface
      * If the $url is just a path, the proxy client class will add a default
      * host name.
      *
-     * @param string $url Path or URL to purge.
+     * @param string $url     Path or URL to purge.
+     * @param array  $headers Extra HTTP headers to send to the caching proxy
+     *                        (optional)
      *
      * @return $this
      */
-    public function purge($url);
+    public function purge($url, array $headers = array());
 }

src/ProxyClient/Nginx.php

@@ -74,10 +74,10 @@ public function refresh($url, array $headers = array())
     /**
      * {@inheritdoc}
      */
-    public function purge($url)
+    public function purge($url, array $headers = array())
     {
         $purgeUrl = $this->purgeLocation.$url;
-        $this->queueRequest(self::HTTP_METHOD_PURGE, $purgeUrl);
+        $this->queueRequest(self::HTTP_METHOD_PURGE, $purgeUrl, $headers);
 
         return $this;
     }

src/ProxyClient/Varnish.php

@@ -109,9 +109,9 @@ public function banPath($path, $contentType = null, $hosts = null)
     /**
      * {@inheritdoc}
      */
-    public function purge($url)
+    public function purge($url, array $headers = array())
     {
-        $this->queueRequest(self::HTTP_METHOD_PURGE, $url);
+        $this->queueRequest(self::HTTP_METHOD_PURGE, $url, $headers);
 
         return $this;
     }

tests/Unit/ProxyClient/VarnishTest.php

@@ -120,9 +120,11 @@ function ($requests) use ($self) {
                         $self->assertEquals('127.0.0.1', $requests[2]->getHost());
                         $self->assertEquals('8080', $requests[2]->getPort());
                         $self->assertEquals('/url/two', $requests[2]->getPath());
+                        $self->assertEquals('bar', $requests[2]->getHeader('X-Foo'));
 
                         $self->assertEquals('123.123.123.2', $requests[3]->getHost());
                         $self->assertEquals('/url/two', $requests[3]->getPath());
+                        $self->assertEquals('bar', $requests[3]->getHeader('X-Foo'));
 
                         return true;
                     }
@@ -138,7 +140,7 @@ function ($requests) use ($self) {
         $varnish = new Varnish($ips, 'my_hostname.dev', $client);
 
         $varnish->purge('/url/one');
-        $varnish->purge('/url/two');
+        $varnish->purge('/url/two', array('X-Foo' => 'bar'));
 
         $varnish->flush();
     }