Merge pull request #36 from Laragear/feat/flexible-caching

[4.x] Adds Flexible Caching

Author: DarkGhostHunter

.stubs/stubs

@@ -10,14 +10,14 @@ namespace Illuminate\Database\Query {
         /**
          * Caches the underlying query results.
          *
-         * @param  \DateTimeInterface|\DateInterval|int|bool|null  $ttl
+         * @param  \DateTimeInterface|\DateInterval|int|bool|array{ 0: \DateTimeInterface|\DateInterval|int, 1: \DateTimeInterface|\DateInterval|int }|null  $ttl
          * @param  string  $key
          * @param  string|null  $store
          * @param  int  $wait
-         * @return static
+         * @return $this
          */
         public function cache(
-            DateTimeInterface|DateInterval|int|bool|null $ttl = null,
+            DateTimeInterface|DateInterval|int|bool|array|null $ttl = null,
             string $key = '',
             string $store = null,
             int $wait = 0,
@@ -37,14 +37,14 @@ namespace Illuminate\Database\Eloquent {
         /**
          * Caches the underlying query results.
          *
-         * @param  \DateTimeInterface|\DateInterval|int|bool|null  $ttl
+         * @param  \DateTimeInterface|\DateInterval|int|bool|array{ 0: \DateTimeInterface|\DateInterval|int, 1: \DateTimeInterface|\DateInterval|int }|null  $ttl
          * @param  string  $key
          * @param  string|null  $store
          * @param  int  $wait
-         * @return static
+         * @return $this
          */
         public function cache(
-            DateTimeInterface|DateInterval|int|bool|null $ttl = null,
+            DateTimeInterface|DateInterval|int|bool|array|null $ttl = null,
             string $key = '',
             string $store = null,
             int $wait = 0,

README.md

@@ -109,7 +109,7 @@ Article::latest('published_at')->take(10)->cache(store: 'redis')->get();
 
 ### Cache Lock (data races)
 
-On multiple processes, the query may be executed multiple times until the first process is able to store the result in the cache, specially when these take more than one second. Take, for example, 1,000 users reading the latest 10 post of a site at the same time will call the database 100 times. 
+On multiple processes, the query may be executed multiple times until the first process is able to store the result in the cache, specially when these take more than one second. Take, for example, 1,000 users reading the latest 10 post of a site at the same time will call the database 1,000 times. 
 
 To avoid this, set the `wait` parameter with the number of seconds to hold the acquired lock.
 
@@ -123,6 +123,16 @@ The first process will acquire the lock for the given seconds and execute the qu
 
 > If you need a more advanced locking mechanism, use the [cache lock](https://laravel.com/docs/cache#managing-locks-across-processes) directly.
 
+### Stale while revalidate
+
+You may take advantage of [Laravel Flexible Caching mechanism](https://laravel.com/docs/11.x/cache#swr) by issuing an array of values as first argument. (...) _The first value in the array represents the number of seconds the cache is considered fresh, while the second value defines how long it can be served as stale data before recalculation is necessary_.
+
+```php
+use App\Models\Article;
+
+Article::latest('published_at')->take(200)->cache([5, 300])->get();
+```
+
 ## Forgetting results with a key
 
 Cache keys are used to identify multiple queries cached with an identifiable name. These are not mandatory, but if you expect to remove a query from the cache, you will need to identify the query with the `key` argument. 

src/CacheAwareConnectionProxy.php

@@ -17,10 +17,13 @@
 use function base64_encode;
 use function cache;
 use function config;
+use function count;
 use function implode;
+use function is_array;
 use function is_int;
 use function max;
 use function md5;
+use function method_exists;
 use function rtrim;
 
 class CacheAwareConnectionProxy extends Connection
@@ -40,7 +43,7 @@ class CacheAwareConnectionProxy extends Connection
     public function __construct(
         public ConnectionInterface $connection,
         protected Repository $repository,
-        protected DateTimeInterface|DateInterval|int|null $ttl,
+        protected DateTimeInterface|DateInterval|int|array|null $ttl,
         protected int $lockWait,
         protected string $cachePrefix,
         public string $userKey = '',
@@ -81,7 +84,11 @@ public function select($query, $bindings = [], $useReadPdo = true)
                 if ($results === null) {
                     $results = $this->connection->select($query, $bindings, $useReadPdo);
 
-                    $this->repository->put($key, $results, $this->ttl);
+                    if (is_array($this->ttl) && count($this->ttl) > 1 && method_exists($this->repository, 'flexible')) {
+                        $this->repository->flexible($key, $results, $this->ttl);
+                    } else {
+                        $this->repository->put($key, $results, $this->ttl);
+                    }
 
                     // If the user added a user key, we will append this computed key to it and save it.
                     if ($this->userKey) {
@@ -181,7 +188,7 @@ protected function getTimestamp(DateInterval|DateTimeInterface|int $expiration):
             return now()->add($expiration)->getTimestamp();
         }
 
-        return now()->addRealSeconds($expiration)->getTimestamp();
+        return now()->addSeconds($expiration)->getTimestamp();
     }
 
     /**
@@ -217,7 +224,7 @@ public function __call($method, $arguments)
      */
     public static function crateNewInstance(
         ConnectionInterface $connection,
-        DateTimeInterface|DateInterval|int|null $ttl,
+        DateTimeInterface|DateInterval|int|array|null $ttl,
         string $key,
         int $wait,
         ?string $store,

src/CacheQuery.php

@@ -75,7 +75,6 @@ protected function getQueries(array $keys): Collection
         $keys = $this->addPrefix($keys);
 
         // Merging the keys last allows us to ensure the parent keys are deleted last.
-        // @phpstan-ignore-next-line
         return Collection::make($this->repository()->getMultiple($keys))->filter()->flatMap->list->merge($keys);
     }
 }

src/CacheQueryServiceProvider.php

@@ -60,15 +60,15 @@ public function boot(): void
     protected function macro(): Closure
     {
         return function (
-            DateTimeInterface|DateInterval|int|bool|null $ttl = 60,
+            DateTimeInterface|DateInterval|int|bool|array|null $ttl = 60,
             string $key = '',
-            string $store = null,
+            ?string $store = null,
             int $wait = 0,
         ): Builder {
             /** @var \Illuminate\Database\Query\Builder $this */
 
             // Avoid re-wrapping the connection into another proxy.
-            if ($this->connection instanceof CacheAwareConnectionProxy) {
+            if ($this->connection instanceof CacheAwareConnectionProxy) { // @phpstan-ignore-line
                 $this->connection = $this->connection->connection;
             }
 
@@ -88,9 +88,9 @@ protected function macro(): Closure
     protected function eloquentMacro(): Closure
     {
         return function (
-            DateTimeInterface|DateInterval|int|bool|null $ttl = 60,
+            DateTimeInterface|DateInterval|int|bool|array|null $ttl = 60,
             string $key = '',
-            string $store = null,
+            ?string $store = null,
             int $wait = 0,
         ): EloquentBuilder {
             /**

tests/CacheAwareConnectionProxyTest.php

@@ -3,6 +3,7 @@
 namespace Tests;
 
 use Closure;
+use Illuminate\Cache\Repository as CacheRepository;
 use Illuminate\Contracts\Cache\Lock;
 use Illuminate\Contracts\Cache\LockProvider;
 use Illuminate\Contracts\Cache\Repository;
@@ -20,6 +21,7 @@
 
 use function floor;
 use function max;
+use function method_exists;
 use function now;
 use function today;
 
@@ -43,6 +45,10 @@ protected function setUp(): void
                 'user_id' => (int) floor(max(1, $i / 2)),
             ])->toArray());
 
+            if (method_exists($this, 'withoutDefer')) {
+                $this->withoutDefer();
+            }
+
             CacheAwareConnectionProxy::$queryHasher = null;
         });
 
@@ -439,6 +445,38 @@ public function test_regenerates_cache_using_ttl_with_negative_number(): void
         static::assertSame('test', $result->name);
     }
 
+    public function test_uses_flexible_caching_when_using_ttl_as_array_of_values(): void
+    {
+        if (! method_exists(CacheRepository::class, 'flexible')) {
+            $this->markTestSkipped('Cannot test flexible caching if repository does not implements it.');
+        }
+
+        $hash = 'cache-query|fj8Xyz4K1Zh0tdAamPbG1A';
+
+        $repository = $this->mock(CacheRepository::class);
+        $repository->expects('put')->never();
+        $repository->expects('flexible')->with($hash, Mockery::type('array'), [5, 300])->once();
+        $repository->expects('getMultiple')->with([$hash, ''])->times(1)->andReturn(['' => null, $hash => null]);
+
+        $this->mock('cache')->shouldReceive('store')->with(null)->andReturn($repository);
+
+        $this->app->make('db')->table('users')->where('id', 1)->cache([5, 300])->first();
+    }
+
+    public function test_doesnt_uses_flexible_caching_if_repository_is_not_flexible(): void
+    {
+        $hash = 'cache-query|fj8Xyz4K1Zh0tdAamPbG1A';
+
+        $repository = $this->mock(Repository::class);
+        $repository->expects('flexible')->never();
+        $repository->expects('put')->with($hash, Mockery::type('array'), [5, 300])->once();
+        $repository->expects('getMultiple')->with([$hash, ''])->times(1)->andReturn(['' => null, $hash => null]);
+
+        $this->mock('cache')->shouldReceive('store')->with(null)->andReturn($repository);
+
+        $this->app->make('db')->table('users')->where('id', 1)->cache([5, 300])->first();
+    }
+
     public function test_different_queries_with_same_key_add_to_same_list(): void
     {
         $this->app->make('db')->table('users')->cache(null, 'foo')->where('id', 1)->first();