cleanup clear

Author: dbu

CHANGELOG.md

@@ -3,6 +3,14 @@ Changelog
 
 See also the [GitHub releases page](https://github.com/FriendsOfSymfony/FOSHttpCache/releases).
 
+2.6.0 (unreleased)
+------------------
+
+### Cache Clear
+
+* Added: ClearCapable to clear the whole cache in one efficient call. Currently
+  supported only by the Symfony HttpCache.
+
 2.5.4
 -----
 

composer.json

@@ -57,7 +57,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "2.5.x-dev"
+            "dev-master": "2.6.x-dev"
         }
     }
 }

doc/invalidation-introduction.rst

@@ -151,5 +151,5 @@ all methods, please refer to proxy specific documentation for the details.
 
     Clear
         Clearing a cache means removing all its cache entries completely. It can be
-        used for a more efficient cache reset rather than banning or purging every
-        URL individually.
+        used for a more efficient cache reset rather than a ban that matches every
+        request or purging every URL individually.

doc/proxy-clients.rst

@@ -31,10 +31,13 @@ Multiplexer   ✓       ✓       ✓       ✓
 
 (1): Only when using `Toflar Psr6Store`_.
 
-
-Of course, you can also implement your own client for other needs. Have a look
+If needed, you can also implement your own client for other needs. Have a look
 at the interfaces in namespace ``FOS\HttpCache\ProxyClient\Invalidation``.
 
+"Clear" can be emulated by "Ban" with a request that matches everything. If
+both are available, "Clear" is preferred as it can be implemented by the
+caching proxy more efficiently.
+
 .. _client setup:
 
 Setup
@@ -318,11 +321,11 @@ Implementation Notes
 --------------------
 
 Each client is an implementation of :source:`ProxyClient <src/ProxyClient/ProxyClient.php>`.
-All other interfaces, ``PurgeCapable``, ``RefreshCapable``, ``BanCapable``, ``ClearCapable`` and
-``TagCapable``, extend this ``ProxyClient``. So each client implements at least
-one of the three :ref:`invalidation methods <invalidation methods>` depending on
+All other interfaces, ``PurgeCapable``, ``RefreshCapable``, ``BanCapable``, ``TagCapable``
+and ``ClearCapable`` extend this ``ProxyClient``. So each client implements at least
+one of the :ref:`invalidation methods <invalidation methods>` depending on
 the proxy server’s abilities. To interact with a proxy client directly, refer to
-the doc comments on the interfaces.
+the phpdoc on the interfaces.
 
 The ``ProxyClient`` has one method: ``flush()``. After collecting
 invalidation requests, ``flush()`` needs to be called to actually send the

src/ProxyClient/Invalidation/ClearCapable.php

@@ -14,19 +14,16 @@
 use FOS\HttpCache\ProxyClient\ProxyClient;
 
 /**
- * An HTTP cache that supports clearing all of its
- * cache entries.
+ * An HTTP cache that supports removing all of its cache entries.
  *
- * Proxy clients supporting this interface can allow
- * for a more efficient delete-all operation rather
- * than banning everything. Also it serves as
- * an alternative to proxies that do not support
- * banning cache entries at all.
+ * This operation allows to clear proxies that do not support banning.
+ * Additionally, this operation is likely more efficient than a ban request
+ * that matches everything.
  */
 interface ClearCapable extends ProxyClient
 {
     /**
-     * Clear the cache completely.
+     * Remove all cache items from this cache.
      *
      * @return $this
      */

src/ProxyClient/MultiplexerClient.php

@@ -14,6 +14,7 @@
 use FOS\HttpCache\Exception\ExceptionCollection;
 use FOS\HttpCache\Exception\InvalidArgumentException;
 use FOS\HttpCache\ProxyClient\Invalidation\BanCapable;
+use FOS\HttpCache\ProxyClient\Invalidation\ClearCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\PurgeCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\RefreshCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\TagCapable;
@@ -23,7 +24,7 @@
  *
  * @author Emanuele Panzeri <[email protected]>
  */
-class MultiplexerClient implements BanCapable, PurgeCapable, RefreshCapable, TagCapable
+class MultiplexerClient implements BanCapable, PurgeCapable, RefreshCapable, TagCapable, ClearCapable
 {
     /**
      * @var ProxyClient[]
@@ -143,6 +144,18 @@ public function refresh($url, array $headers = [])
         return $this;
     }
 
+    /**
+     * Forwards to all clients.
+     *
+     * @return $this
+     */
+    public function clear()
+    {
+        $this->invoke(ClearCapable::class, 'clear', []);
+
+        return $this;
+    }
+
     /**
      * Invoke the given $method on all available ProxyClients implementing the
      * given $interface.

src/ProxyClient/Symfony.php

@@ -74,11 +74,7 @@ protected function configureOptions()
     }
 
     /**
-     * Remove/Expire cache objects based on cache tags.
-     *
-     * @param array $tags Tags that should be removed/expired from the cache
-     *
-     * @return $this
+     * {@inheritdoc}
      */
     public function invalidateTags(array $tags)
     {
@@ -99,7 +95,10 @@ public function invalidateTags(array $tags)
     }
 
     /**
-     * Clear the cache completely.
+     * {@inheritdoc}
+     *
+     * Clearing the cache is implemented with a purge request with a special
+     * header to indicate that the whole cache should be removed.
      *
      * @return $this
      */
@@ -110,5 +109,7 @@ public function clear()
             [$this->options['clear_cache_header'] => 'true'],
             false
         );
+
+        return $this;
     }
 }

tests/Unit/ProxyClient/MultiplexerClientTest.php

@@ -12,6 +12,7 @@
 namespace FOS\HttpCache\Tests\Unit\ProxyClient;
 
 use FOS\HttpCache\ProxyClient\Invalidation\BanCapable;
+use FOS\HttpCache\ProxyClient\Invalidation\ClearCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\PurgeCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\RefreshCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\TagCapable;
@@ -134,6 +135,7 @@ public function testPurge()
             ->getMock();
         $mockClient2 = \Mockery::mock(PurgeCapable::class)
             ->shouldReceive('purge')
+            ->once()
             ->with($url, $headers)
             ->getMock();
         $mockClient3 = \Mockery::mock(ProxyClient::class);
@@ -143,6 +145,23 @@ public function testPurge()
         $this->assertSame($multiplexer, $multiplexer->purge($url, $headers));
     }
 
+    public function testClear()
+    {
+        $mockClient1 = \Mockery::mock(ClearCapable::class)
+            ->shouldReceive('clear')
+            ->once()
+            ->getMock();
+        $mockClient2 = \Mockery::mock(ClearCapable::class)
+            ->shouldReceive('clear')
+            ->once()
+            ->getMock();
+        $mockClient3 = \Mockery::mock(ProxyClient::class);
+
+        $multiplexer = new MultiplexerClient([$mockClient1, $mockClient2, $mockClient3]);
+
+        $this->assertSame($multiplexer, $multiplexer->clear());
+    }
+
     public function provideInvalidClient()
     {
         return [