Merge pull request #440 from FriendsOfSymfony/clear-cache

Clear cache with ClearCapable

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

@@ -148,3 +148,8 @@ all methods, please refer to proxy specific documentation for the details.
         invalidation, such as selecting content to be banned by regular expressions.
         This opens the way for powerful invalidation schemes, such as tagging cache
         entries.
+
+    Clear
+        Clearing a cache means removing all its cache entries completely. It can be
+        used for a more efficient cache reset rather than a ban that matches every
+        request or purging every URL individually.

doc/proxy-clients.rst

@@ -19,19 +19,25 @@ Supported invalidation methods
 Not all clients support all :ref:`invalidation methods <invalidation methods>`.
 This table provides of methods supported by each proxy client:
 
-============= ======= ======= ======= =======
-Client        Purge   Refresh Ban     Tagging
-============= ======= ======= ======= =======
+============= ======= ======= ======= ======= =======
+Client        Purge   Refresh Ban     Tagging Clear
+============= ======= ======= ======= ======= =======
 Varnish       ✓       ✓       ✓       ✓
 NGINX         ✓       ✓
-Symfony Cache ✓       ✓               ✓
+Symfony Cache ✓       ✓               ✓ (1)   ✓ (1)
 Noop          ✓       ✓       ✓       ✓
 Multiplexer   ✓       ✓       ✓       ✓
-============= ======= ======= ======= =======
+============= ======= ======= ======= ======= =======
 
-Of course, you can also implement your own client for other needs. Have a look
+(1): Only when using `Toflar Psr6Store`_.
+
+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
@@ -315,11 +321,11 @@ Implementation Notes
 --------------------
 
 Each client is an implementation of :source:`ProxyClient <src/ProxyClient/ProxyClient.php>`.
-All other interfaces, ``PurgeCapable``, ``RefreshCapable``, ``BanCapable`` 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
@@ -332,3 +338,4 @@ requests.
 .. _in the HTTPlug documentation: http://php-http.readthedocs.io/en/latest/clients.html
 .. _HTTPlug plugins: http://php-http.readthedocs.io/en/latest/plugins/index.html
 .. _message factory and URI factory: http://php-http.readthedocs.io/en/latest/message/message-factory.html
+.. _Toflar Psr6Store: https://github.com/Toflar/psr6-symfony-http-cache-store

src/CacheInvalidator.php

@@ -17,6 +17,7 @@
 use FOS\HttpCache\Exception\ProxyUnreachableException;
 use FOS\HttpCache\Exception\UnsupportedProxyOperationException;
 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;
@@ -55,6 +56,11 @@ class CacheInvalidator
      */
     const TAGS = 'tags';
 
+    /**
+     * Value to check support of clearCache operation.
+     */
+    const CLEAR = 'clear';
+
     /**
      * @var ProxyClient
      */
@@ -105,6 +111,8 @@ public function supports($operation)
                 }
 
                 return $supports;
+            case self::CLEAR:
+                return $this->cache instanceof ClearCapable;
             default:
                 throw new InvalidArgumentException('Unknown operation '.$operation);
         }
@@ -264,6 +272,24 @@ public function invalidateRegex($path, $contentType = null, $hosts = null)
         return $this;
     }
 
+    /**
+     * Clear the cache completely.
+     *
+     * @throws UnsupportedProxyOperationException if HTTP cache does not support clearing the cache completely
+     *
+     * @return $this
+     */
+    public function clearCache()
+    {
+        if (!$this->cache instanceof ClearCapable) {
+            throw UnsupportedProxyOperationException::cacheDoesNotImplement('CLEAR');
+        }
+
+        $this->cache->clear();
+
+        return $this;
+    }
+
     /**
      * Send all pending invalidation requests.
      *

src/ProxyClient/Invalidation/ClearCapable.php

@@ -0,0 +1,31 @@
+<?php
+
+/*
+ * This file is part of the FOSHttpCache package.
+ *
+ * (c) FriendsOfSymfony <http://friendsofsymfony.github.com/>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace FOS\HttpCache\ProxyClient\Invalidation;
+
+use FOS\HttpCache\ProxyClient\ProxyClient;
+
+/**
+ * An HTTP cache that supports removing all of its cache entries.
+ *
+ * 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
+{
+    /**
+     * Remove all cache items from this cache.
+     *
+     * @return $this
+     */
+    public function clear();
+}

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

@@ -11,6 +11,7 @@
 
 namespace FOS\HttpCache\ProxyClient;
 
+use FOS\HttpCache\ProxyClient\Invalidation\ClearCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\PurgeCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\RefreshCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\TagCapable;
@@ -26,7 +27,7 @@
  * @author David de Boer <[email protected]>
  * @author David Buchmann <[email protected]>
  */
-class Symfony extends HttpProxyClient implements PurgeCapable, RefreshCapable, TagCapable
+class Symfony extends HttpProxyClient implements PurgeCapable, RefreshCapable, TagCapable, ClearCapable
 {
     const HTTP_METHOD_REFRESH = 'GET';
 
@@ -56,12 +57,14 @@ protected function configureOptions()
         $resolver = parent::configureOptions();
         $resolver->setDefaults([
             'purge_method' => PurgeListener::DEFAULT_PURGE_METHOD,
+            'clear_cache_header' => PurgeListener::DEFAULT_CLEAR_CACHE_HEADER,
             'tags_method' => PurgeTagsListener::DEFAULT_TAGS_METHOD,
             'tags_header' => PurgeTagsListener::DEFAULT_TAGS_HEADER,
             'tags_invalidate_path' => '/',
             'header_length' => 7500,
         ]);
         $resolver->setAllowedTypes('purge_method', 'string');
+        $resolver->setAllowedTypes('clear_cache_header', 'string');
         $resolver->setAllowedTypes('tags_method', 'string');
         $resolver->setAllowedTypes('tags_header', 'string');
         $resolver->setAllowedTypes('tags_invalidate_path', 'string');
@@ -71,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)
     {
@@ -94,4 +93,23 @@ public function invalidateTags(array $tags)
 
         return $this;
     }
+
+    /**
+     * {@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
+     */
+    public function clear()
+    {
+        $this->queueRequest(
+            $this->options['purge_method'], '/',
+            [$this->options['clear_cache_header'] => 'true'],
+            false
+        );
+
+        return $this;
+    }
 }

src/SymfonyCache/PurgeListener.php

@@ -13,25 +13,36 @@
 
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\OptionsResolver\OptionsResolver;
+use Toflar\Psr6HttpCacheStore\Psr6StoreInterface;
 
 /**
  * Purge handler for the symfony built-in HttpCache.
  *
  * @author David Buchmann <[email protected]>
+ * @author Yanick Witschi <[email protected]>
  *
  * {@inheritdoc}
  */
 class PurgeListener extends AccessControlledListener
 {
     const DEFAULT_PURGE_METHOD = 'PURGE';
 
+    const DEFAULT_CLEAR_CACHE_HEADER = 'Clear-Cache';
+
     /**
      * The purge method to use.
      *
      * @var string
      */
     private $purgeMethod;
 
+    /**
+     * The clear cache header to use.
+     *
+     * @var string
+     */
+    private $clearCacheHeader;
+
     /**
      * When creating the purge listener, you can configure an additional option.
      *
@@ -47,7 +58,9 @@ public function __construct(array $options = [])
     {
         parent::__construct($options);
 
-        $this->purgeMethod = $this->getOptionsResolver()->resolve($options)['purge_method'];
+        $options = $this->getOptionsResolver()->resolve($options);
+        $this->purgeMethod = $options['purge_method'];
+        $this->clearCacheHeader = $options['clear_cache_header'];
     }
 
     /**
@@ -83,6 +96,24 @@ public function handlePurge(CacheEvent $event)
         $response = new Response();
         $store = $event->getKernel()->getStore();
 
+        // Purge whole cache
+        if ($request->headers->has($this->clearCacheHeader)) {
+            if (!$store instanceof Psr6StoreInterface) {
+                $response->setStatusCode(400);
+                $response->setContent('Store must be an instance of '.Psr6StoreInterface::class.'. Please check your proxy configuration.');
+                $event->setResponse($response);
+
+                return;
+            }
+
+            $store->prune();
+
+            $response->setStatusCode(200, 'Pruned');
+            $event->setResponse($response);
+
+            return;
+        }
+
         if ($store->purge($request->getUri())) {
             $response->setStatusCode(200, 'Purged');
         } else {
@@ -100,7 +131,9 @@ protected function getOptionsResolver()
     {
         $resolver = parent::getOptionsResolver();
         $resolver->setDefault('purge_method', static::DEFAULT_PURGE_METHOD);
+        $resolver->setDefault('clear_cache_header', static::DEFAULT_CLEAR_CACHE_HEADER);
         $resolver->setAllowedTypes('purge_method', 'string');
+        $resolver->setAllowedTypes('clear_cache_header', 'string');
 
         return $resolver;
     }

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 [