wip

Author: freekmurze

config/responsecache.php

@@ -6,45 +6,35 @@
      */
     'enabled' => env('RESPONSE_CACHE_ENABLED', true),
 
-    /*
-     * Cache configuration settings
-     */
     'cache' => [
         /*
-         * Here you may define the cache store that should be used to store
-         * requests. This can be the name of any store that is
-         * configured in app/config/cache.php
+         * Here you may define the cache store that should be used
+         * to store requests. This can be the name of any store
+         * that is configured in your app's cache.php config
          */
         'store' => env('RESPONSE_CACHE_DRIVER', 'file'),
 
         /*
-         * When using the default CacheRequestFilter this setting controls the
-         * default number of seconds responses must be cached.
+         * The default number of seconds responses will be cached
+         * when using the default CacheProfile settings.
          */
         'lifetime_in_seconds' => (int) env('RESPONSE_CACHE_LIFETIME', 60 * 60 * 24 * 7),
 
         /*
-         * If the cache driver you configured supports tags, you may specify a tag name
-         * here. All responses will be tagged. When clearing the responsecache only
-         * items with that tag will be flushed.
+         * If your cache driver supports tags, you may specify a tag
+         * name here. All responses will be tagged. When clearing
+         * the responsecache only items with that tag flushed.
          *
          * You may use a string or an array here.
          */
         'tag' => env('RESPONSE_CACHE_TAG', ''),
     ],
 
-    /*
-     * Cache bypass header configuration
-     */
     'bypass' => [
         /*
-         * Whether cache bypass functionality is enabled
-         */
-        'enabled' => env('CACHE_BYPASS_HEADER_NAME') !== null,
-
-        /*
-         * The header name that will force a cache bypass.
-         * This can be useful to monitor the performance of your application.
+         * The header name that will force a bypass of the cache.
+         * This is useful when you want to see the performance
+         * of your application without the caching enabled.
          */
         'header_name' => env('CACHE_BYPASS_HEADER_NAME'),
 
@@ -54,42 +44,42 @@
         'header_value' => env('CACHE_BYPASS_HEADER_VALUE'),
     ],
 
-    /*
-     * Debug and development settings
-     */
     'debug' => [
         /*
-         * This setting determines if a http header named with the cache time
-         * should be added to a cached response. This can be handy when
-         * debugging.
+         * Determines if debug headers are added to cached
+         * responses. This can be handy for debugging how
+         * response caching is performing in your app.
+         */
+        'enabled' => env('APP_DEBUG', false),
+
+        /*
+         * The name of the http header containing the
+         * point at which the response was cached.
          */
-        'add_time_header' => env('APP_DEBUG', false),
+        'cache_time_header_name' => 'X-Cache-Time',
 
         /*
-         * This setting determines the name of the http header that contains
-         * the time at which the response was cached
+         * The name of the header for the cache status that
+         * indicates whether a response was HIT or MISS.
          */
-        'time_header_name' => env('RESPONSE_CACHE_HEADER_NAME', 'laravel-responsecache'),
+        'cache_status_header_name' => 'X-Cache-Status',
 
         /*
-         * This setting determines if a http header named with the cache age
-         * should be added to a cached response. This can be handy when
-         * debugging.
-         * ONLY works when "add_time_header" is also active!
+         * The header name for the cache age in seconds.
          */
-        'add_age_header' => env('RESPONSE_CACHE_AGE_HEADER', false),
+        'cache_age_header_name' => 'X-Cache-Age',
 
         /*
-         * This setting determines the name of the http header that contains
-         * the age of cache
+         * The header name used for the response cache key.
+         * This is only added when app.debug is enabled.
          */
-        'age_header_name' => env('RESPONSE_CACHE_AGE_HEADER_NAME', 'laravel-responsecache-age'),
+        'cache_key_header_name' => 'X-Cache-Key',
     ],
 
     /*
-     * Query parameters listed here will be ignored when generating the cache key.
-     * This is useful for tracking parameters like UTM tags or gclid that don't
-     * affect the page content but would otherwise create separate cache entries.
+     * These query parameters will be ignored when generating
+     * the cache key. This is useful for ignoring tracking
+     * parameters like UTM tags, gclid and also fbclid.
      */
     'ignored_query_parameters' => [
         'utm_source',
@@ -102,21 +92,15 @@
     ],
 
     /*
-     * Customization - Class implementations
-     */
-
-    /*
-     *  The given class will determinate if a request should be cached. The
-     *  default class will cache all successful GET-requests.
-     *
-     *  You can provide your own class given that it implements the
-     *  CacheProfile interface.
+     * The given class determines if a request should be cached.
+     * By default all successful GET-requests will be cached.
+     * You can provide your own by using the CacheProfile.
      */
     'cache_profile' => Spatie\ResponseCache\CacheProfiles\CacheAllSuccessfulGetRequests::class,
 
     /*
-     * This class is responsible for generating a hash for a request. This hash
-     * is used to look up a cached response.
+     * This class is responsible for generating a hash for
+     * a request. Used for looking up cached responses.
      */
     'hasher' => \Spatie\ResponseCache\Hasher\DefaultHasher::class,
 
@@ -126,8 +110,9 @@
     'serializer' => \Spatie\ResponseCache\Serializers\JsonSerializer::class,
 
     /*
-     * Here you may define replacers that dynamically replace content from the response.
-     * Each replacer must implement the Replacer interface.
+     * Here you may define the replacers that will replace
+     * dynamic content from the response. Each replacer
+     * must always implement the Replacer interface.
      */
     'replacers' => [
         \Spatie\ResponseCache\Replacers\CsrfTokenReplacer::class,

docs/advanced-usage/configuration.md

@@ -53,17 +53,22 @@ Set this to an empty array if you want all query parameters to be included in th
 
 ## Debug headers
 
-When `APP_DEBUG` is `true`, the package adds a header to cached responses showing when the response was cached. You can customize this behavior.
+When `APP_DEBUG` is `true`, the package adds debug headers to cached responses. You can customize this behavior.
 
 ```php
 // config/responsecache.php
 
 'debug' => [
-    'add_time_header' => env('APP_DEBUG', false),
-    'time_header_name' => 'laravel-responsecache',
-    'add_age_header' => env('RESPONSE_CACHE_AGE_HEADER', false),
-    'age_header_name' => 'laravel-responsecache-age',
+    'enabled' => env('APP_DEBUG', false),
+    'cache_time_header_name' => 'X-Cache-Time',
+    'cache_status_header_name' => 'X-Cache-Status',
+    'cache_age_header_name' => 'X-Cache-Age',
+    'cache_key_header_name' => 'X-Cache-Key',
 ],
 ```
 
-When `add_age_header` is enabled (requires `add_time_header` to also be active), cached responses will include a header showing how many seconds ago the response was cached.
+When enabled, cached responses will include the following headers:
+- `X-Cache-Status`: `HIT` or `MISS` indicating whether the response was served from cache
+- `X-Cache-Time`: the timestamp when the response was cached
+- `X-Cache-Age`: how many seconds ago the response was cached (only on cache hits)
+- `X-Cache-Key`: the cache key used (only when `app.debug` is `true`)

docs/advanced-usage/custom-cache-profiles.md

@@ -10,7 +10,6 @@ You can create your own cache profile by implementing the `CacheProfile` interfa
 ```php
 namespace App\CacheProfiles;
 
-use DateTime;
 use Illuminate\Http\Request;
 use Spatie\ResponseCache\CacheProfiles\CacheProfile;
 use Symfony\Component\HttpFoundation\Response;
@@ -33,9 +32,9 @@ class CustomCacheProfile implements CacheProfile
         return $response->isSuccessful();
     }
 
-    public function cacheRequestUntil(Request $request): DateTime
+    public function cacheLifetimeInSeconds(Request $request): int
     {
-        return now()->addMinutes(30);
+        return 30 * 60;
     }
 
     public function useCacheNameSuffix(Request $request): string

docs/basic-usage/caching-responses.md

@@ -26,9 +26,6 @@ Route::get('/posts', [PostController::class, 'index'])
 Route::get('/posts/{post}', [PostController::class, 'show'])
     ->middleware(CacheResponse::for(hours(1), tags: ['posts']));
 
-// Cache with a specific driver
-Route::get('/api/posts', [ApiPostController::class, 'index'])
-    ->middleware(CacheResponse::for(minutes(5), tags: ['api', 'posts'], driver: 'redis'));
 ```
 
 The `lifetime` parameter accepts Laravel's `minutes()`, `hours()`, and `days()` helpers (or any `CarbonInterval`), or an `int` in seconds.
@@ -48,7 +45,7 @@ class PostController
         return view('posts.index', ['posts' => Post::all()]);
     }
 
-    #[Cache(lifetime: 10 * 60, driver: 'redis')]
+    #[Cache(lifetime: 10 * 60)]
     public function show(Post $post)
     {
         return view('posts.show', ['post' => $post]);
@@ -59,7 +56,6 @@ class PostController
 The `#[Cache]` attribute accepts the following parameters.
 - `lifetime`: Cache duration in seconds (defaults to the config value)
 - `tags`: Cache tags (array)
-- `driver`: Cache driver to use (defaults to the config value)
 
 Attributes can also be applied at the class level to cache all methods in the controller.
 

docs/installation-setup.md

@@ -55,16 +55,16 @@ return [
     ],
 
     'bypass' => [
-        'enabled' => env('CACHE_BYPASS_HEADER_NAME') !== null,
         'header_name' => env('CACHE_BYPASS_HEADER_NAME'),
         'header_value' => env('CACHE_BYPASS_HEADER_VALUE'),
     ],
 
     'debug' => [
-        'add_time_header' => env('APP_DEBUG', false),
-        'time_header_name' => env('RESPONSE_CACHE_HEADER_NAME', 'laravel-responsecache'),
-        'add_age_header' => env('RESPONSE_CACHE_AGE_HEADER', false),
-        'age_header_name' => env('RESPONSE_CACHE_AGE_HEADER_NAME', 'laravel-responsecache-age'),
+        'enabled' => env('APP_DEBUG', false),
+        'cache_time_header_name' => 'X-Cache-Time',
+        'cache_status_header_name' => 'X-Cache-Status',
+        'cache_age_header_name' => 'X-Cache-Age',
+        'cache_key_header_name' => 'X-Cache-Key',
     ],
 
     'ignored_query_parameters' => [

freek-blog-full.png

@@ -10,6 +10,5 @@ class Cache
     public function __construct(
         public ?int $lifetime = null,
         public array $tags = [],
-        public ?string $driver = null,
     ) {}
 }

src/Attributes/Cache.php

@@ -7,16 +7,9 @@
 #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
 class FlexibleCache
 {
-    public int $fresh;
-
-    public int $stale;
-
     public function __construct(
         public int $lifetime,
         public int $grace,
         public array $tags = [],
-    ) {
-        $this->fresh = $lifetime;
-        $this->stale = $grace;
-    }
+    ) {}
 }

src/Attributes/FlexibleCache.php

@@ -17,21 +17,21 @@ abstract class AbstractRequestBuilder
 
     protected ?string $cacheNameSuffix = null;
 
-    public function withPutMethod(): self
+    public function withPutMethod(): static
     {
         $this->method = 'PUT';
 
         return $this;
     }
 
-    public function withPatchMethod(): self
+    public function withPatchMethod(): static
     {
         $this->method = 'PATCH';
 
         return $this;
     }
 
-    public function withPostMethod(): self
+    public function withPostMethod(): static
     {
         $this->method = 'POST';
 
@@ -42,21 +42,21 @@ public function withPostMethod(): self
      * if method is GET then will be converted to query
      * otherwise it will became part of request input
      */
-    public function withParameters(array $parameters): self
+    public function withParameters(array $parameters): static
     {
         $this->parameters = $parameters;
 
         return $this;
     }
 
-    public function withCookies(array $cookies): self
+    public function withCookies(array $cookies): static
     {
         $this->cookies = $cookies;
 
         return $this;
     }
 
-    public function withHeaders(array $headers): self
+    public function withHeaders(array $headers): static
     {
         $this->server = collect($this->server)
             ->filter(fn (string $val, string $key) => ! str_starts_with($key, 'HTTP_'))
@@ -69,14 +69,14 @@ public function withHeaders(array $headers): self
         return $this;
     }
 
-    public function withRemoteAddress($remoteAddress): self
+    public function withRemoteAddress(string $remoteAddress): static
     {
         $this->server['REMOTE_ADDR'] = $remoteAddress;
 
         return $this;
     }
 
-    public function usingSuffix($cacheNameSuffix): self
+    public function usingSuffix(string $cacheNameSuffix): static
     {
         $this->cacheNameSuffix = $cacheNameSuffix;
 

src/CacheItemSelector/AbstractRequestBuilder.php

@@ -41,7 +41,6 @@ public function forget(): void
 
                 return $this->hasher->getHashFor($request);
             })
-            ->filter(fn ($hash) => $this->taggedCache($this->tags)->has($hash))
             ->each(fn ($hash) => $this->taggedCache($this->tags)->forget($hash));
     }
 }