[13.x] Cache::touch() & Store::touch() for TTL Extension (#55954)

* :feat: add touch for cache ttl extension

* :test: fix failing memoized store test

* :clean: remove inadvertent inclusions

* :test: remove unnecessary imports in tests

* formatting

* formatting

* fix fake

* adjust wording

---------

Co-authored-by: Yitz Willroth <ewillroth@insomniacookies.com>
Co-authored-by: Taylor Otwell <taylor@laravel.com>

Author: 3 people

src/Illuminate/Cache/ApcStore.php

@@ -92,6 +92,24 @@ public function forever($key, $value)
         return $this->put($key, $value, 0);
     }
 
+    /**
+     * Adjust the expiration time of a cached item.
+     *
+     * @param  string  $key
+     * @param  int  $seconds
+     * @return bool
+     */
+    public function touch($key, $seconds)
+    {
+        $value = $this->apc->get($key = $this->getPrefix().$key);
+
+        if (is_null($value)) {
+            return false;
+        }
+
+        return $this->apc->put($key, $value, $seconds);
+    }
+
     /**
      * Remove an item from the cache.
      *

src/Illuminate/Cache/ArrayStore.php

@@ -3,6 +3,7 @@
 namespace Illuminate\Cache;
 
 use Illuminate\Contracts\Cache\LockProvider;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Carbon;
 use Illuminate\Support\InteractsWithTime;
 
@@ -130,6 +131,28 @@ public function forever($key, $value)
         return $this->put($key, $value, 0);
     }
 
+    /**
+     * Adjust the expiration time of a cached item.
+     *
+     * @param  string  $key
+     * @param  int  $seconds
+     * @return bool
+     */
+    public function touch($key, $seconds)
+    {
+        $item = Arr::get($this->storage, $key = $this->getPrefix().$key, null);
+
+        if (is_null($item)) {
+            return false;
+        }
+
+        $item['expiresAt'] = $this->calculateExpiration($seconds);
+
+        $this->storage = array_merge($this->storage, [$key => $item]);
+
+        return true;
+    }
+
     /**
      * Remove an item from the cache.
      *

src/Illuminate/Cache/DatabaseStore.php

@@ -352,6 +352,21 @@ public function restoreLock($name, $owner)
         return $this->lock($name, 0, $owner);
     }
 
+    /**
+     * Adjust the expiration time of a cached item.
+     *
+     * @param  string  $key
+     * @param  int  $seconds
+     * @return bool
+     */
+    public function touch($key, $seconds)
+    {
+        return (bool) $this->table()
+            ->where('key', '=', $this->getPrefix().$key)
+            ->where('expiration', '>', $now = $this->getTime())
+            ->update(['expiration' => $now + $seconds]);
+    }
+
     /**
      * Remove an item from the cache.
      *

src/Illuminate/Cache/DynamoDbStore.php

@@ -428,6 +428,43 @@ public function restoreLock($name, $owner)
         return $this->lock($name, 0, $owner);
     }
 
+    /**
+     * Adjust the expiration time of a cached item.
+     *
+     * @param  string  $key
+     * @param  int  $seconds
+     * @return bool
+     *
+     * @throws DynamoDbException
+     */
+    public function touch($key, $seconds)
+    {
+        try {
+            $this->dynamo->updateItem([
+                'TableName' => $this->table,
+                'Key' => [$this->keyAttribute => ['S' => $this->getPrefix().$key]],
+                'UpdateExpression' => 'SET #expiry = :expiry',
+                'ConditionExpression' => 'attribute_exists(#key) AND #expiry > :now',
+                'ExpressionAttributeNames' => [
+                    '#key' => $this->keyAttribute,
+                    '#expiry' => $this->expirationAttribute,
+                ],
+                'ExpressionAttributeValues' => [
+                    ':expiry' => ['N' => (string) $this->toTimestamp($seconds)],
+                    ':now' => ['N' => (string) $this->currentTime()],
+                ],
+            ]);
+        } catch (DynamoDbException $e) {
+            if (str_contains($e->getMessage(), 'ConditionalCheckFailed')) {
+                return false;
+            }
+
+            throw $e;
+        }
+
+        return true;
+    }
+
     /**
      * Remove an item from the cache.
      *

src/Illuminate/Cache/FileStore.php

@@ -238,6 +238,24 @@ public function restoreLock($name, $owner)
         return $this->lock($name, 0, $owner);
     }
 
+    /**
+     * Adjust the expiration time of a cached item.
+     *
+     * @param  string  $key
+     * @param  int  $seconds
+     * @return bool
+     */
+    public function touch($key, $seconds)
+    {
+        $payload = $this->getPayload($this->getPrefix().$key);
+
+        if (is_null($payload['data'])) {
+            return false;
+        }
+
+        return $this->put($key, $payload['data'], $seconds);
+    }
+
     /**
      * Remove an item from the cache.
      *

src/Illuminate/Cache/MemcachedStore.php

@@ -202,6 +202,18 @@ public function restoreLock($name, $owner)
         return $this->lock($name, 0, $owner);
     }
 
+    /**
+     * Adjust the expiration time of a cached item.
+     *
+     * @param  string  $key
+     * @param  int  $seconds
+     * @return bool
+     */
+    public function touch($key, $seconds)
+    {
+        return $this->memcached->touch($this->getPrefix().$key, $this->calculateExpiration($seconds));
+    }
+
     /**
      * Remove an item from the cache.
      *

src/Illuminate/Cache/MemoizedStore.php

@@ -196,6 +196,20 @@ public function restoreLock($name, $owner)
         return $this->repository->resoreLock(...func_get_args());
     }
 
+    /**
+     * Adjust the expiration time of a cached item.
+     *
+     * @param  string  $key
+     * @param  int  $seconds
+     * @return bool
+     */
+    public function touch($key, $seconds)
+    {
+        unset($this->cache[$this->prefix($key)]);
+
+        return $this->repository->touch($key, $seconds);
+    }
+
     /**
      * Remove an item from the cache.
      *

src/Illuminate/Cache/NullStore.php

@@ -93,6 +93,18 @@ public function restoreLock($name, $owner)
         return $this->lock($name, 0, $owner);
     }
 
+    /**
+     * Adjust the expiration time of a cached item.
+     *
+     * @param  string  $key
+     * @param  int  $seconds
+     * @return bool
+     */
+    public function touch($key, $seconds)
+    {
+        return false;
+    }
+
     /**
      * Remove an item from the cache.
      *

src/Illuminate/Cache/RedisStore.php

@@ -248,6 +248,18 @@ public function restoreLock($name, $owner)
         return $this->lock($name, 0, $owner);
     }
 
+    /**
+     * Adjust the expiration time of a cached item.
+     *
+     * @param  string  $key
+     * @param  int  $seconds
+     * @return bool
+     */
+    public function touch($key, $seconds)
+    {
+        return (bool) $this->connection()->expire($this->getPrefix().$key, (int) max(1, $seconds));
+    }
+
     /**
      * Remove an item from the cache.
      *

src/Illuminate/Cache/Repository.php

@@ -526,6 +526,26 @@ public function flexible($key, $ttl, $callback, $lock = null, $alwaysDefer = fal
         return $value;
     }
 
+    /**
+     * Set the expiration of a cached item; null TTL will retain the item forever.
+     *
+     * @param  string  $key
+     * @param  \DateTimeInterface|\DateInterval|int|null  $ttl
+     * @return bool
+     */
+    public function touch($key, $ttl = null)
+    {
+        $value = $this->get($key);
+
+        if (is_null($value)) {
+            return false;
+        }
+
+        return is_null($ttl)
+            ? $this->forever($key, $value)
+            : $this->store->touch($this->itemKey($key), $this->getSeconds($ttl));
+    }
+
     /**
      * Remove an item from the cache.
      *