Merge pull request #30 from Toflar/feature/disable-content-digests

Added support for disabling generating content digests

Author: Toflar

README.md

@@ -112,6 +112,40 @@ passing an array of `$options` in the constructor:
 
   **Type**: `string`
   **Default**: `Cache-Tags`
+
+* **generate_content_digests**: Whether or not content digests should be generated.
+  See "Generating Content Digests" for more information.
+
+  **Type**: `boolean`
+  **Default**: `true`
+  
+### Generating Content Digests
+
+By default, this cache implementation generates content digests.
+This means that the response meta data is stored separately from the
+response content. If multiple responses share the same content, it
+is stored in the cache only once.
+Compare the following illustrations to see the difference:
+
+**With generating content digests**:
+![Illustration of the cache with generating content digests](docs/with_content_digests.svg)
+
+**Without generating content digests**:
+![Illustration of the cache without generating content digests](docs/without_content_digests.svg)
+
+Generating content digests optimizes the cache so it uses up less
+storage. Using them, however, also comes at the costs of requiring
+a second round trip to fetch the content digest from the cache during
+the lookup process.
+
+Whether or not you want to use content digests depends on your PSR-6
+cache back end. If lookups are fast and storage is rather limited (e.g. Redis),
+you might want to use content digests. If lookups are rather slow and
+storage is less of an issue (e.g. Filesystem), you might want to disable
+them.
+
+You can control the behaviour using the `generate_content_digests` configuration
+option.
 
 ### Caching `BinaryFileResponse` Instances
 

docs/with_content_digests.svg

@@ -87,6 +87,9 @@ public function __construct(array $options = [])
         $resolver->setDefault('cache_tags_header', 'Cache-Tags')
             ->setAllowedTypes('cache_tags_header', 'string');
 
+        $resolver->setDefault('generate_content_digests', true)
+            ->setAllowedTypes('generate_content_digests', 'boolean');
+
         $resolver->setDefault('cache', function (Options $options) {
             if (!isset($options['cache_directory'])) {
                 throw new MissingOptionsException('The cache_directory option is required unless you set the cache explicitly');
@@ -198,12 +201,18 @@ public function write(Request $request, Response $response)
         }
 
         // Add or replace entry with current Vary header key
-        $entries[$this->getVaryKey($response->getVary(), $request)] = [
+        $varyKey = $this->getVaryKey($response->getVary(), $request);
+        $entries[$varyKey] = [
             'vary' => $response->getVary(),
             'headers' => $headers,
             'status' => $response->getStatusCode(),
         ];
 
+        // Add content if content digests are disabled
+        if (!$this->options['generate_content_digests']) {
+            $entries[$varyKey]['content'] = $response->getContent();
+        }
+
         // If the response has a Vary header we remove the non-varying entry
         if ($response->hasVary()) {
             unset($entries[self::NON_VARYING_KEY]);
@@ -412,7 +421,7 @@ public function getCacheKey(Request $request)
     }
 
     /**
-     * @return string
+     * @return string|null
      *
      * @internal Do not use in public code, this is for unit testing purposes only
      */
@@ -422,6 +431,10 @@ public function generateContentDigest(Response $response)
             return 'bf'.hash_file('sha256', $response->getFile()->getPathname());
         }
 
+        if (!$this->options['generate_content_digests']) {
+            return null;
+        }
+
         return 'en'.hash('sha256', $response->getContent());
     }
 
@@ -465,6 +478,11 @@ private function saveContentDigest(Response $response)
         }
 
         $contentDigest = $this->generateContentDigest($response);
+
+        if (null === $contentDigest) {
+            return;
+        }
+
         $digestCacheItem = $this->cache->getItem($contentDigest);
 
         if ($digestCacheItem->isHit()) {
@@ -575,7 +593,18 @@ private function restoreResponse(array $cacheData)
         // Unset internal debug info
         unset($cacheData['headers'][self::CACHE_DEBUG_HEADER]);
 
+        // Check for content digest header
         if (!isset($cacheData['headers']['x-content-digest'][0])) {
+            // No digest was generated but the content was stored inline
+            if (isset($cacheData['content'])) {
+                return new Response(
+                    $cacheData['content'],
+                    $cacheData['status'],
+                    $cacheData['headers']
+                );
+            }
+
+            // No content digest and no inline content means we cannot restore the response
             return null;
         }