Added cache bypass/renew option

Author: Arnaud Coolsaet

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "brightfish/caching-guzzle",
     "description": "Cache HTTP responses through Guzzle middleware",
-    "version": "1.1.1",
+    "version": "1.2.0",
     "type": "library",
     "keywords": ["guzzle", "middleware", "cache", "laravel", "http-cache"],
     "license": "GPL-3.0-only",

readme.md

@@ -5,104 +5,103 @@
 [![StyleCI](https://styleci.io/repos/175029173/shield)](https://styleci.io/repos/175029173)
 [![Packagist](https://img.shields.io/packagist/dt/brightfish/caching-guzzle?label=Total%20downloads&style=flat-square)](https://packagist.org/packages/brightfish/caching-guzzle)
 
-Simple caching middleware for Guzzle, works well with Laravel or with any cache system 
-implementing the PSR-16 caching interface.  
+Simple caching middleware for [Guzzle](https://github.com/guzzle/guzzle/), works well with [Laravel](https://github.com/laravel) or with any cache system 
+implementing the [PSR-16 caching interface](https://www.php-fig.org/psr/psr-16/).  
 
 ## Installation
 ```
 composer require brightfish/caching-guzzle
 ```
 
-## Using the middleware
+## Usage
+The registration of the caching middleware follows [Guzzle's documentation](http://docs.guzzlephp.org/en/stable/handlers-and-middleware.html#handlers).
+
 ```
 use GuzzleHttp\Client;
 use GuzzleHttp\HandlerStack;
 use Brightfish\CachingGuzzle\Middleware;
 
+/** @var \Psr\SimpleCache\CacheInterface $store */
 $store = app('cache')->store('database'); // Laravel
-$handler = new Middleware($store, 3600);
+
+$handler = new Middleware($store);
+
 $stack = HandlerStack::create();
+
 $stack->push($handler);
+
 $client = new Client([
     'handler' => $stack,
     'base_uri' => 'https://example.org/api/'
 ]);
 ```
 
-## Making requests and retrieving from cache
+### Instantiation parameters
+Instantiating the middleware takes 3 parameters: `new Middleware($store, $ttl = 60, $log = true)`, where only `$store`, a `SimpleCache` implementation is required. `$ttl` is the default cache duration, which can be overridden by each request. And finally, if `$log` is true, cache hits will be written to Laravel's log or the `error_log` defined by PHP (see [source](https://github.com/brightfish-be/caching-guzzle/blob/c0e96ae157b4e17363eb76ee5996995fbf0bd4a5/src/Middleware.php#L168)).
+
+
+## Making requests
+
+**Available options:**   
+
+| Option | Type | Default | Description |
+|:-------|------|---------|:------------|
+|`cache` | bool | `true` | Completely disable the cache for this request |
+|`cache_anew` | bool | `false` | Bypass the cache and replace it with the new response |
+|`cache_ttl` | int | `60` | Cache duration in seconds, use `-1` to cache forever |
+|`cache_key` | string | `true` | Cache key to override the default one based on the request URI (see [Cache retrieval](https://github.com/brightfish-be/caching-guzzle#cache-retrieval)) |
+
+### Cache the response for 60s (default)
 ```
-# This response will be cached for 60s (same as default).
 $response_1 = $client->get('resource', [
     'cache_ttl' => 60
 ]);
-
-# This response will not be cached.
+```
+### Request anew and update the cache
+```
+$response_3 = $client->post('resource/84', [
+    'cache_anew' => false
+]);
+```
+### Disable caching
+```
 $response_2 = $client->post('resource/84', [
     'cache' => false
 ]);
-
-# This response will be cached forever with a custom key.
-$response_3 = $client->post('resource/84', [
+```
+### Cache forever with a custom key
+```
+$response_4 = $client->post('resource/84', [
     'cache_key' => 'my-key',
     'cache_ttl' => -1
 ]);
+```
+If `cache_ttl` is set to `0` the response will not be cached, but, contrary to `'cache' => false`, it may be retrieved from it.
 
+## Cache retrieval
+```
 # Get response_1 from cache.
 $cached_response_1 = $store->get('//example.org/api/resource');
 
-# Get response_3 from cache.
-$cached_response_3 = $store->get('my-key');
+# Get response_4 from cache.
+$cached_response_4 = $store->get('my-key');
 ```
 
 ## Using the wrapper
-Instead of manually configuring the Guzzle client and the caching middleware, it is also possible
-to instantiate the Client class provided in this package. This way, the binding of the middleware is done for you.
-```
-use Brightfish\CachingGuzzle\Client;
-
-$client = new Client($psrCompatibleCache, [
-    'cache_ttl' => 3600,
-    'cache_log' => false,
-    'base_uri' => 'https://example.org/api/'
-]);
-```
-
-## Available options
-
-### Per request
-
-- `$cache` (bool): whether to disable the cache for this specific request.
-- `$cache_ttl` (int): cache duration in seconds for this response, use `-1` to cache forever.
-- `$cache_key` (string): custom cache key to override the default one based on the request URI.
-
-```
-$response_1 = $client->get('resource', [
-    'cache' => false,
-    'cache_ttl' => 3600
-]);
-```
-
-### When instantiating the middleware
-
-- `$cache` (\Psr\SimpleCache\CacheInterface): cache handler implementation.
-- `$ttl` (int): default cache duration in seconds [default: 60].
-- `$log` (bool): whether to log the cache requests [default: false].  
+Instead of manually configuring Guzzle's client and the caching middleware, it is also possible to instantiate the `Client` class provided by this package. This way, the binding of the middleware is done for you.
 
 ```
-$handler = new CacheMiddleware($cache, $ttl, $log);
-```
-
-### When instantiating the wrapper, pass options along with the Guzzle ones
+use Brightfish\CachingGuzzle\Client;
 
-- `$cache` (\Psr\SimpleCache\CacheInterface): cache handler implementation.
-- `$cache_ttl` (int): default cache duration in seconds [default: 60].
-- `$cache_log` (bool): whether to log the cache requests [default: false].
+/** @var \Psr\SimpleCache\CacheInterface $store */
+$psrCompatibleCache = new Cache();
 
-```
-$client = new Client($cache, [
-    'cache_ttl' => 12345,
-    'cache_log' => true,
+$client = new Client($psrCompatibleCache, [
+    'cache_ttl' => 60,	   // default cache duration
+    'cache_log' => false,  // log the cache hits
+    // Guzzle options:
     'base_uri' => 'https://example.org/api/'
+    // ...
 ]);
 ```
 

src/Client.php

@@ -16,8 +16,8 @@ class Client extends GuzzleClient
 {
     /**
      * Create a middleware stack and instantiate Guzzle.
-     * {@inheritdoc}
-     * @param array $config
+     * {@inheritDoc}
+     * @param CacheInterface $cache
      */
     public function __construct(CacheInterface $cache, array $config = [])
     {
@@ -30,7 +30,13 @@ public function __construct(CacheInterface $cache, array $config = [])
 
         $config['handler']->push(new Middleware($cache, $ttl, $log));
 
-        unset($config['cache'], $config['cache_ttl'], $config['cache_log'], $config['cache_key']);
+        unset(
+            $config['cache'],
+            $config['cache_anew'],
+            $config['cache_ttl'],
+            $config['cache_log'],
+            $config['cache_key']
+        );
 
         parent::__construct($config);
     }

src/Middleware.php

@@ -39,9 +39,9 @@ class Middleware
 
     /**
      * Cache the laravel cache driver instance.
-     * @param CacheInterface $cache             Cache handler implementation
-     * @param int $ttl                          Default cache duration in seconds
-     * @param bool $log                         Whether to log the cache requests
+     * @param CacheInterface $cache Cache handler implementation
+     * @param int $ttl Default cache duration in seconds
+     * @param bool $log Whether to log the cache requests
      */
     public function __construct(CacheInterface $cache, int $ttl = 60, bool $log = false)
     {
@@ -58,11 +58,19 @@ public function __construct(CacheInterface $cache, int $ttl = 60, bool $log = fa
     public function __invoke(callable $handler): callable
     {
         return function (RequestInterface $request, array $options) use (&$handler) {
+            # By default caching is allowed, else return early
+            if (!($options['cache'] ?? true)) {
+                return $handler($request, $options);
+            }
+
             # Create the cache key
-            $key = $this->makeKey($options, $request->getUri());
+            $key = $this->getKey($request->getUri(), $options['cache_key'] ?? '');
+
+            # Should we bypass current cached value?
+            $bypass = $options['cache_anew'] ?? false;
 
             # Try to get from cache
-            if ($key && $entry = $this->get($key)) {
+            if (!$bypass && $entry = $this->get($key)) {
                 return $entry;
             }
 
@@ -71,7 +79,7 @@ public function __invoke(callable $handler): callable
 
             return $promise->then(
                 function (ResponseInterface $response) use ($options, $key) {
-                    if ($key && $ttl = $this->getTTL($options)) {
+                    if ($ttl = $this->getTTL($options)) {
                         $this->save($key, $response, $ttl);
                     }
 
@@ -82,20 +90,14 @@ function (ResponseInterface $response) use ($options, $key) {
     }
 
     /**
-     * Create the key which will reference the cache entry.
-     * @param array $options
+     * Either return the custom passed key or the request URL minus the protocol.
      * @param UriInterface $uri
+     * @param string $key
      * @return string
      */
-    protected function makeKey(array $options, UriInterface $uri): string
+    protected function getKey(UriInterface $uri, string $key = ''): string
     {
-        # Does the specific request allow caching?
-        $cache = $options['cache'] ?? true;
-
-        # Either return the custom passed key or the request URL minus the protocol.
-        return $cache
-            ? ($options['cache_key'] ?? preg_replace('#(https?:)#', '', (string)$uri))
-            : '';
+        return $key ?: preg_replace('#(https?:)#', '', (string)$uri);
     }
 
     /**

tests/Feature/MiddlewareFeatureTest.php

@@ -17,22 +17,14 @@ class MiddlewareFeatureTest extends FeatureTestCase
     const TEST_URL = 'https://duckduckgo.com/';
 
     /** @var string */
-    const TEST_STR = 'I\'m a duck!';
+    const TEST_STR_1 = 'I\'m a duck!';
+
+    const TEST_STR_2 = 'I\'m a duck too!';
 
     public function test_caching()
     {
-        $middleware = new Middleware($this->store, 3600);
-
-        $mock = new MockHandler([
-            new Response(200, [], static::TEST_STR),
-            new Response(200, [], static::TEST_STR)
-        ]);
-
-        $stack = HandlerStack::create($mock);
-        $stack->push($middleware);
-
-        $client = new Client([
-            'handler' => $stack
+        $client = $this->getClientWithMockResponses([
+            static::TEST_STR_1,
         ]);
 
         $client->get(static::TEST_URL);
@@ -41,33 +33,45 @@ public function test_caching()
 
         $cached = $this->store->get($key);
 
-        $this->assertStringContainsString(static::TEST_STR, $cached);
+        $this->assertStringContainsString(static::TEST_STR_1, $cached);
+    }
 
-        # Request with custom key
+    public function test_caching_with_custom_key()
+    {
+        $client = $this->getClientWithMockResponses([
+            static::TEST_STR_2,
+        ]);
 
         $client->get(static::TEST_URL, ['cache_key' => 'test_key']);
 
         $cached = $this->store->get('test_key');
 
-        $this->assertStringContainsString(static::TEST_STR, $cached);
-
-        // echo PHP_EOL . 'MiddlewareFeatureTest response: ' . $cached . PHP_EOL;
+        $this->assertStringContainsString(static::TEST_STR_2, $cached);
     }
 
-    public function test_caching_with_promised_request()
+    public function test_caching_anew()
     {
-        $middleware = new Middleware($this->store, 3600);
+        $client = $this->getClientWithMockResponses([
+            static::TEST_STR_1,
+            static::TEST_STR_2,
+        ]);
 
-        $mock = new MockHandler([
-            new Response(200, [], static::TEST_STR),
-            new Response(200, [], static::TEST_STR)
+        $client->get(static::TEST_URL);
+
+        $client->get(static::TEST_URL, [
+            'cache_anew' => true,
+            'cache_key' => 'test_key',
         ]);
 
-        $stack = HandlerStack::create($mock);
-        $stack->push($middleware);
+        $cached = $this->store->get('test_key');
 
-        $client = new Client([
-            'handler' => $stack
+        $this->assertStringContainsString(static::TEST_STR_2, $cached);
+    }
+
+    public function test_caching_with_promised_request()
+    {
+        $client = $this->getClientWithMockResponses([
+            static::TEST_STR_1,
         ]);
 
         $promises = [
@@ -78,7 +82,7 @@ public function test_caching_with_promised_request()
 
         $this->assertEquals(
             (string)$responses['prom_1']->getBody(),
-            static::TEST_STR
+            static::TEST_STR_1
         );
     }
 }