SWR feature #506

Marcel-Wil · 2025-12-14T22:01:00Z

Added Flexible caching with stale-while-revalidate (SWR) for the package. To see how to use it look at the added parts of Readme

Added tests to test new SWR feature

freekmurze

In general, I like the changes, but I think (you can correct me if I'm wrong), that AI played a big part in creating this. Let's polish it some more, so it feels hand crafted.

src/Middlewares/CacheResponse.php

freekmurze · 2025-12-15T09:28:54Z

README.md

+
+The package supports flexible caching with stale-while-revalidate behavior using explicit middleware. With SWR, cached responses have two time periods:
+
+- **Fresh period**: The cache is considered fresh and served immediately without revalidation


Nitpick: nowhere in our docs, we use bold styling for highlighting parameters. I presume this was AI generated. Remove this bold styling and try to follow the stying of the rest of the readme.

freekmurze · 2025-12-15T09:31:15Z

README.md


+### Flexible caching with stale-while-revalidate (SWR)
+
+The package supports flexible caching with stale-while-revalidate behavior using explicit middleware. With SWR, cached responses have two time periods:


I think there's a high chance that people don't know what stale-while-revalidate is. We should explain better in human language what this exactly does. Try to give a nice example. Link to the Laravel docs so people can also check out Laravel's docs on flexible. Make it as if you explain this all to a newcomer 🙂

freekmurze · 2025-12-15T09:33:38Z

tests/FlexibleResponseCacheTest.php

+    Carbon::setTestNow();
+});
+
+describe('fresh cache period', function () {


I used this is AI generated. In our tests suites, we don't use describe, remove it.

I would be find with all the tests in one file, but if you feel it would be better split up, create a directory, flexibleCache with multiple test files.

freekmurze · 2025-12-15T09:34:11Z

tests/FlexibleResponseCacheTest.php

+use Spatie\ResponseCache\Events\ResponseCacheHit;
+
+beforeEach(function () {
+    // Use array driver for time-based tests and tag support


This comment is unnecessary.

freekmurze · 2025-12-15T09:42:43Z

README.md

+
+// Fresh for 3 minutes, then stale for 15 minutes
+Route::get('/api/posts', 'PostController@index')
+    ->middleware(CacheResponse::flexible(180, 900));


It's hard to know what does numbers are, let's use named arguments in this example to improve readability.

freekmurze · 2025-12-15T09:44:28Z

README.md

+    ->middleware(CacheResponse::flexible(180, 900, false, 'posts', 'api'));
+```
+
+The `flexible()` method accepts:


Instead of giving all examples first, and then explaining all parameters, it would be more readable to give a simple example, explain that fully. And then introduce another parameter, give an example for the new parameter and so on.

That will feel a lot more "human" that what we have now.

freekmurze · 2025-12-15T09:46:55Z

tests/TestCase.php

            return 'dummy response';
        })->middleware('cacheResponse:300');
+
+        // Flexible cache routes for SWR testing


Remove this comment, it doesn't add any value. Instead use a Route group, in which you set the /flexible prefix.

freekmurze · 2025-12-15T09:48:17Z

src/Middlewares/CacheResponse.php

+        $deferFlag = $defer ? '1' : '0';
+        $flexibleTime = "{$freshSeconds}:{$totalSeconds}:{$deferFlag}";
+
+        if (empty($tags)) {


I think this is not that readable.

We should build up a base string, and then if you use tags, concatenate the extra string needed to that base string.

freekmurze · 2025-12-15T09:50:19Z

src/Middlewares/CacheResponse.php

+     * @param string ...$tags Optional cache tags
+     * @return string
+     */
+    public static function flexible(int $freshSeconds, int $totalSeconds, bool $defer = false, ...$tags): string


It's not common to have a middleware with two public methods. Let's extract this to a dedicated middleware FlexibleCacheResponse. That will make it easier in usage, and the make the middleware simpler. Maybe it could extend of a BaseCacheMiddleware where common logic lives.

freekmurze

It's moving in the right direction. 👍

Here are a few more nitpicks / ideas.

freekmurze · 2025-12-17T09:22:16Z

src/Middlewares/BaseCacheMiddleware.php

+
+    public function addCacheAgeHeader(Response $response): Response
+    {
+        if (config('responsecache.add_cache_age_header') and $time = $response->headers->get(config('responsecache.cache_time_header_name'))) {


we don't use and mostly. Replace it with &&

Actually let's make that && go away, by adding a nested if, that will make it more readable.

freekmurze · 2025-12-17T09:23:57Z

src/Middlewares/CacheResponse.php

-                $response = $this->getCachedResponse($request, $tags);
-                if ($response !== false) {
-                    return $response;
+        if ($this->responseCache->enabled($request) && ! $this->responseCache->shouldBypass($request)) {


Also refactor that && away by adding an extra nested if

freekmurze · 2025-12-17T09:24:25Z

src/Middlewares/CacheResponse.php

+            }

-            $response->headers->set(config('responsecache.cache_age_header_name'), $ageInSeconds);
+            if (is_string($middleware) && str_starts_with($middleware, FlexibleCacheResponse::class.':')) {


Nested ifs are preferred here too

freekmurze · 2025-12-17T09:38:06Z

src/Middlewares/FlexibleCacheResponse.php

+     * @param string ...$tags Optional cache tags
+     * @return string
+     */
+    public static function flexible(int $freshSeconds, int $totalSeconds, bool $defer = false, ...$tags): string


This might be a big one, in addition to accept int's and use them as seconds, let's add support for users to pass CarbonInterval as well, so people on the latest version of the frame work can use those nifty new seconds() minutes(), ... helper functions.

freekmurze · 2025-12-17T09:39:10Z

src/Middlewares/FlexibleCacheResponse.php

+
+        $response = $this->responseCache->flexible(
+            $cacheKey,
+            [$flexibleTime[0], $flexibleTime[1]],


I don't know what inside those indexes by looking here. Extract those to a named variable.

freekmurze · 2025-12-17T09:40:51Z

README.md

-// Fresh for 3 minutes, then stale for 15 minutes
+use Spatie\ResponseCache\Middlewares\FlexibleCacheResponse;
+
+/* Simple example how to use the flexible method: 


This first line can be omitted, hold no value. You can add it as the text above the code block.

freekmurze · 2025-12-17T09:41:30Z

README.md

+use Spatie\ResponseCache\Middlewares\FlexibleCacheResponse;
+
+/* Simple example how to use the flexible method: 
+/* between 0-180 seconds we will always serve fresh data from the cache 


Let's polish this by making these proper sentences: make these start with a capital, and with a .

freekmurze · 2025-12-17T09:42:01Z

README.md

+
+/* Simple example how to use the flexible method: 
+/* between 0-180 seconds we will always serve fresh data from the cache 
+/* after 180 seconds we will serve "old" data and send new data to recalculate to the server


Here also make it more readable by adding a comma. "After 180 seconds, we will..." Also do this for any other comments.

freekmurze · 2025-12-17T09:42:12Z

README.md

+/* on the next request if the new data is processed by the server we will serve the new data until
+/* then we serve old "stale" data
+*/
+int $freshSeconds = 180;


This isn't valid PHP remove it.

freekmurze · 2025-12-17T09:43:10Z

README.md

+int $staleSeconds = 900;
 Route::get('/api/posts', 'PostController@index')
-    ->middleware(CacheResponse::flexible(180, 900));
+    ->middleware(FlexibleCacheResponse::flexible($freshSeconds, $staleSeconds));


Here you can use name arguments to more clearly convey what the flexible method expects.

When we have support for CarbonInterval, you could also use those new second(), minutes() functions in this example.

Marcel-Wil requested a review from freekmurze December 14, 2025 22:01

freekmurze requested changes Dec 15, 2025

View reviewed changes

freekmurze reviewed Dec 17, 2025

View reviewed changes

Marcel-Wil closed this Jan 16, 2026

Marcel-Wil force-pushed the main branch from 9a11a5f to a8ae03f Compare January 16, 2026 11:47


		The package supports flexible caching with stale-while-revalidate behavior using explicit middleware. With SWR, cached responses have two time periods:

		- Fresh period: The cache is considered fresh and served immediately without revalidation


		### Flexible caching with stale-while-revalidate (SWR)

		The package supports flexible caching with stale-while-revalidate behavior using explicit middleware. With SWR, cached responses have two time periods:

Uh oh!

SWR feature #506

SWR feature #506

Uh oh!

Conversation

Marcel-Wil commented Dec 14, 2025

Uh oh!

freekmurze left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

freekmurze left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants