From d401e64ea146a079b2d9974c7b04725fcca23a8c Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Fri, 8 May 2026 16:35:04 +0400 Subject: [PATCH 1/4] feat: add cache touch support --- src/Cache/Adapter.php | 7 +++++++ src/Cache/Adapter/Filesystem.php | 12 ++++++++++++ src/Cache/Adapter/Hazelcast.php | 19 +++++++++++++++++++ src/Cache/Adapter/Memcached.php | 19 +++++++++++++++++++ src/Cache/Adapter/Memory.php | 19 +++++++++++++++++++ src/Cache/Adapter/None.php | 10 ++++++++++ src/Cache/Adapter/Pool.php | 10 ++++++++++ src/Cache/Adapter/Redis.php | 19 +++++++++++++++++++ src/Cache/Adapter/RedisCluster.php | 21 ++++++++++++++++++++- src/Cache/Adapter/Sharding.php | 10 ++++++++++ src/Cache/Cache.php | 23 +++++++++++++++++++++++ tests/Cache/Base.php | 12 ++++++++++++ tests/Cache/NoneTest.php | 5 +++++ 13 files changed, 185 insertions(+), 1 deletion(-) diff --git a/src/Cache/Adapter.php b/src/Cache/Adapter.php index a1ea41e2b7..91aa22d68a 100644 --- a/src/Cache/Adapter.php +++ b/src/Cache/Adapter.php @@ -24,6 +24,13 @@ interface Adapter */ public function save(string $key, array|string $data, string $hash = ''): bool|string|array; + /** + * @param string $key + * @param string $hash optional + * @return bool + */ + public function touch(string $key, string $hash = ''): bool; + /** * @param string $key * @return string[] diff --git a/src/Cache/Adapter/Filesystem.php b/src/Cache/Adapter/Filesystem.php index b07c01203f..43fb5ed631 100644 --- a/src/Cache/Adapter/Filesystem.php +++ b/src/Cache/Adapter/Filesystem.php @@ -97,6 +97,18 @@ class Filesystem implements Adapter } } + /** + * @param string $key + * @param string $hash optional + * @return bool + */ + public function touch(string $key, string $hash = ''): bool + { + $file = $this->getPath($key); + + return file_exists($file) && touch($file); + } + /** * @param string $key * @return string[] diff --git a/src/Cache/Adapter/Hazelcast.php b/src/Cache/Adapter/Hazelcast.php index 2a696c0958..c43e3957f5 100644 --- a/src/Cache/Adapter/Hazelcast.php +++ b/src/Cache/Adapter/Hazelcast.php @@ -87,6 +87,25 @@ class Hazelcast implements Adapter return ($this->execute(fn () => $this->memcached->set($key, json_encode($cache)))) ? $data : false; } + /** + * @param string $key + * @param string $hash optional + * @return bool + */ + public function touch(string $key, string $hash = ''): bool + { + $data = $this->load($key, PHP_INT_MAX, $hash); + if ($data === false) { + return false; + } + + if (! is_string($data) && ! is_array($data)) { + return false; + } + + return $this->save($key, $data, $hash) !== false; + } + /** * @param string $key * @return string[] diff --git a/src/Cache/Adapter/Memcached.php b/src/Cache/Adapter/Memcached.php index 98363c2e3f..b5d040b837 100644 --- a/src/Cache/Adapter/Memcached.php +++ b/src/Cache/Adapter/Memcached.php @@ -89,6 +89,25 @@ class Memcached implements Adapter return $this->execute(fn () => $this->memcached->set($key, $cache)) ? $data : false; } + /** + * @param string $key + * @param string $hash optional + * @return bool + */ + public function touch(string $key, string $hash = ''): bool + { + $data = $this->load($key, PHP_INT_MAX, $hash); + if ($data === false) { + return false; + } + + if (! is_string($data) && ! is_array($data)) { + return false; + } + + return $this->save($key, $data, $hash) !== false; + } + /** * @param string $key * @return string[] diff --git a/src/Cache/Adapter/Memory.php b/src/Cache/Adapter/Memory.php index 63c084281b..b4e99bb613 100644 --- a/src/Cache/Adapter/Memory.php +++ b/src/Cache/Adapter/Memory.php @@ -76,6 +76,25 @@ class Memory implements Adapter return $data; } + /** + * @param string $key + * @param string $hash optional + * @return bool + */ + public function touch(string $key, string $hash = ''): bool + { + $data = $this->load($key, PHP_INT_MAX, $hash); + if ($data === false) { + return false; + } + + if (! is_string($data) && ! is_array($data)) { + return false; + } + + return $this->save($key, $data, $hash) !== false; + } + /** * @param string $key * @return string[] diff --git a/src/Cache/Adapter/None.php b/src/Cache/Adapter/None.php index a3bb629f58..76ec9ff672 100644 --- a/src/Cache/Adapter/None.php +++ b/src/Cache/Adapter/None.php @@ -53,6 +53,16 @@ class None implements Adapter return false; } + /** + * @param string $key + * @param string $hash optional + * @return bool + */ + public function touch(string $key, string $hash = ''): bool + { + return false; + } + /** * @param string $key * @return string[] diff --git a/src/Cache/Adapter/Pool.php b/src/Cache/Adapter/Pool.php index 2fa228bf3e..851069830b 100644 --- a/src/Cache/Adapter/Pool.php +++ b/src/Cache/Adapter/Pool.php @@ -59,6 +59,16 @@ class Pool implements Adapter return $result; } + public function touch(string $key, string $hash = ''): bool + { + /** + * @var bool $result + */ + $result = $this->delegate(__FUNCTION__, \func_get_args()); + + return $result; + } + public function list(string $key): array { /** diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index 3c0683f8b2..5b48a5abd0 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -152,6 +152,25 @@ class Redis implements Adapter } } + /** + * @param string $key + * @param string $hash optional + * @return bool + */ + public function touch(string $key, string $hash = ''): bool + { + $data = $this->load($key, PHP_INT_MAX, $hash); + if ($data === false) { + return false; + } + + if (! is_string($data) && ! is_array($data)) { + return false; + } + + return $this->save($key, $data, $hash) !== false; + } + /** * @param string $key * @return string[] diff --git a/src/Cache/Adapter/RedisCluster.php b/src/Cache/Adapter/RedisCluster.php index 186fe3f7d0..0056a77051 100644 --- a/src/Cache/Adapter/RedisCluster.php +++ b/src/Cache/Adapter/RedisCluster.php @@ -103,7 +103,7 @@ class RedisCluster implements Adapter /** @var string|false */ $redis_string = $this->execute(fn () => $this->redis->hGet($key, $hash)); - if ($redis_string === false) { + if ($redis_string === false || ! is_string($redis_string)) { return false; } @@ -151,6 +151,25 @@ class RedisCluster implements Adapter } } + /** + * @param string $key + * @param string $hash optional + * @return bool + */ + public function touch(string $key, string $hash = ''): bool + { + $data = $this->load($key, PHP_INT_MAX, $hash); + if ($data === false) { + return false; + } + + if (! is_string($data) && ! is_array($data)) { + return false; + } + + return $this->save($key, $data, $hash) !== false; + } + /** * @param string $key * @return string[] diff --git a/src/Cache/Adapter/Sharding.php b/src/Cache/Adapter/Sharding.php index a036b8972f..0521edff6a 100644 --- a/src/Cache/Adapter/Sharding.php +++ b/src/Cache/Adapter/Sharding.php @@ -92,6 +92,16 @@ class Sharding implements Adapter return $this->getAdapter($key)->save($key, $data, $hash); } + /** + * @param string $key + * @param string $hash optional + * @return bool + */ + public function touch(string $key, string $hash = ''): bool + { + return $this->getAdapter($key)->touch($key, $hash); + } + /** * @param string $key * @return string[] diff --git a/src/Cache/Cache.php b/src/Cache/Cache.php index 416e1e5118..324fb71da1 100644 --- a/src/Cache/Cache.php +++ b/src/Cache/Cache.php @@ -106,6 +106,29 @@ class Cache } } + /** + * Refresh a cache entry timestamp without replacing its data. + * + * @param string $key + * @param string $hash optional + * @return bool + */ + public function touch(string $key, string $hash = ''): bool + { + $key = $this->caseSensitive ? $key : strtolower($key); + $hash = $this->caseSensitive ? $hash : strtolower($hash); + + $start = microtime(true); + $result = $this->adapter->touch($key, $hash); + $duration = microtime(true) - $start; + $this->operationDuration?->record($duration, [ + 'operation' => 'touch', + 'adapter' => $this->adapter->getName($key), + ]); + + return $result; + } + /** * Returns a list of keys. * diff --git a/tests/Cache/Base.php b/tests/Cache/Base.php index eecfdf5278..6f90730d00 100644 --- a/tests/Cache/Base.php +++ b/tests/Cache/Base.php @@ -57,6 +57,18 @@ abstract class Base extends TestCase $this->assertEquals(false, $data); } + public function testCacheTouch(): void + { + $result = self::$cache->save('touch-key', 'touch data', 'touch-key'); + $this->assertEquals('touch data', $result); + + $this->assertEquals(true, self::$cache->touch('touch-key', 'touch-key')); + $this->assertEquals('touch data', self::$cache->load('touch-key', 60, 'touch-key')); + $this->assertEquals(false, self::$cache->touch('missing-touch-key', 'missing-touch-key')); + + self::$cache->purge('touch-key'); + } + public function testCaseInsensitivity(): void { // Ensure case in-sensitivity first (configured in adapter's setUp) diff --git a/tests/Cache/NoneTest.php b/tests/Cache/NoneTest.php index bf86461969..0eb57886a8 100644 --- a/tests/Cache/NoneTest.php +++ b/tests/Cache/NoneTest.php @@ -60,6 +60,11 @@ class NoneTest extends Base $this->assertEquals(true, $result); } + public function testCacheTouch(): void + { + $this->assertEquals(false, self::$cache->touch($this->key)); + } + public function testCaseInsensitivity(): void { // None adapter does not expect case sensitivity/insensitivy From c6293e25f02e9b6b48deed9d5e55f00a79179562 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Fri, 8 May 2026 16:42:37 +0400 Subject: [PATCH 2/4] fix: allow touching expired cache entries --- src/Cache/Adapter/Hazelcast.php | 14 ++++++++------ src/Cache/Adapter/Memcached.php | 11 +++++------ src/Cache/Adapter/Memory.php | 12 ++++++------ src/Cache/Adapter/Redis.php | 18 ++++++++++++++---- src/Cache/Adapter/RedisCluster.php | 19 +++++++++++++++---- tests/Cache/MemoryTest.php | 16 ++++++++++++++++ 6 files changed, 64 insertions(+), 26 deletions(-) diff --git a/src/Cache/Adapter/Hazelcast.php b/src/Cache/Adapter/Hazelcast.php index c43e3957f5..6818c069bb 100644 --- a/src/Cache/Adapter/Hazelcast.php +++ b/src/Cache/Adapter/Hazelcast.php @@ -94,16 +94,18 @@ class Hazelcast implements Adapter */ public function touch(string $key, string $hash = ''): bool { - $data = $this->load($key, PHP_INT_MAX, $hash); - if ($data === false) { + $cache = $this->execute(fn () => $this->memcached->get($key)); + if (is_string($cache)) { + $cache = json_decode($cache, true); + } + + if (! is_array($cache)) { return false; } - if (! is_string($data) && ! is_array($data)) { - return false; - } + $cache['time'] = time(); - return $this->save($key, $data, $hash) !== false; + return (bool) $this->execute(fn () => $this->memcached->set($key, json_encode($cache))); } /** diff --git a/src/Cache/Adapter/Memcached.php b/src/Cache/Adapter/Memcached.php index b5d040b837..b80aa3fec0 100644 --- a/src/Cache/Adapter/Memcached.php +++ b/src/Cache/Adapter/Memcached.php @@ -96,16 +96,15 @@ class Memcached implements Adapter */ public function touch(string $key, string $hash = ''): bool { - $data = $this->load($key, PHP_INT_MAX, $hash); - if ($data === false) { + /** @var array{time: int, data: string|array}|false */ + $cache = $this->execute(fn () => $this->memcached->get($key)); + if ($cache === false) { return false; } - if (! is_string($data) && ! is_array($data)) { - return false; - } + $cache['time'] = time(); - return $this->save($key, $data, $hash) !== false; + return (bool) $this->execute(fn () => $this->memcached->set($key, $cache)); } /** diff --git a/src/Cache/Adapter/Memory.php b/src/Cache/Adapter/Memory.php index b4e99bb613..bb4a82a92d 100644 --- a/src/Cache/Adapter/Memory.php +++ b/src/Cache/Adapter/Memory.php @@ -83,16 +83,16 @@ class Memory implements Adapter */ public function touch(string $key, string $hash = ''): bool { - $data = $this->load($key, PHP_INT_MAX, $hash); - if ($data === false) { + if (empty($key) || ! isset($this->store[$key])) { return false; } - if (! is_string($data) && ! is_array($data)) { - return false; - } + /** @var array{time: int, data: string|array} $saved */ + $saved = $this->store[$key]; + $saved['time'] = time(); + $this->store[$key] = $saved; - return $this->save($key, $data, $hash) !== false; + return true; } /** diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index 5b48a5abd0..654da4cffa 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -159,16 +159,26 @@ class Redis implements Adapter */ public function touch(string $key, string $hash = ''): bool { - $data = $this->load($key, PHP_INT_MAX, $hash); - if ($data === false) { + if (empty($hash)) { + $hash = $key; + } + + $redis_string = $this->execute(fn () => $this->redis->hGet($key, $hash)); + + if ($redis_string === false || $redis_string === null || ! is_string($redis_string)) { return false; } - if (! is_string($data) && ! is_array($data)) { + try { + /** @var array{time: int, data: mixed} $cache */ + $cache = json_decode($redis_string, true, flags: JSON_THROW_ON_ERROR); + $cache['time'] = time(); + $value = json_encode($cache, flags: JSON_THROW_ON_ERROR); + } catch (Throwable $th) { return false; } - return $this->save($key, $data, $hash) !== false; + return $this->execute(fn () => $this->redis->hSet($key, $hash, $value)) !== false; } /** diff --git a/src/Cache/Adapter/RedisCluster.php b/src/Cache/Adapter/RedisCluster.php index 0056a77051..7dcd4b51d5 100644 --- a/src/Cache/Adapter/RedisCluster.php +++ b/src/Cache/Adapter/RedisCluster.php @@ -158,16 +158,27 @@ class RedisCluster implements Adapter */ public function touch(string $key, string $hash = ''): bool { - $data = $this->load($key, PHP_INT_MAX, $hash); - if ($data === false) { + if (empty($hash)) { + $hash = $key; + } + + /** @var string|false */ + $redis_string = $this->execute(fn () => $this->redis->hGet($key, $hash)); + + if ($redis_string === false || ! is_string($redis_string)) { return false; } - if (! is_string($data) && ! is_array($data)) { + try { + /** @var array{time: int, data: mixed} $cache */ + $cache = json_decode($redis_string, true, flags: JSON_THROW_ON_ERROR); + $cache['time'] = time(); + $value = json_encode($cache, flags: JSON_THROW_ON_ERROR); + } catch (Throwable $th) { return false; } - return $this->save($key, $data, $hash) !== false; + return $this->execute(fn () => $this->redis->hSet($key, $hash, $value)) !== false; } /** diff --git a/tests/Cache/MemoryTest.php b/tests/Cache/MemoryTest.php index b3e2a7683b..6b99ffd117 100644 --- a/tests/Cache/MemoryTest.php +++ b/tests/Cache/MemoryTest.php @@ -20,4 +20,20 @@ class MemoryTest extends Base self::$cache->save('test:file36', 'file36'); $this->assertEquals(4, self::$cache->getSize()); } + + public function testTouchExpiredEntry(): void + { + $adapter = new Memory(); + $cache = new Cache($adapter); + + $cache->save('expired-touch-key', 'expired data'); + /** @var array{time: int, data: string} $stored */ + $stored = $adapter->store['expired-touch-key']; + $stored['time'] = time() - 10; + $adapter->store['expired-touch-key'] = $stored; + + $this->assertEquals(false, $cache->load('expired-touch-key', 1)); + $this->assertEquals(true, $cache->touch('expired-touch-key')); + $this->assertEquals('expired data', $cache->load('expired-touch-key', 1)); + } } From bef0ec00c4cb105798f83f3b26edf158713ef9ec Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Fri, 8 May 2026 16:45:22 +0400 Subject: [PATCH 3/4] test: verify touch refreshes stale entries --- tests/Cache/Base.php | 5 ++++- tests/Cache/MemoryTest.php | 16 ---------------- 2 files changed, 4 insertions(+), 17 deletions(-) diff --git a/tests/Cache/Base.php b/tests/Cache/Base.php index 6f90730d00..d5f9f013ba 100644 --- a/tests/Cache/Base.php +++ b/tests/Cache/Base.php @@ -62,8 +62,11 @@ abstract class Base extends TestCase $result = self::$cache->save('touch-key', 'touch data', 'touch-key'); $this->assertEquals('touch data', $result); + sleep(2); + + $this->assertEquals(false, self::$cache->load('touch-key', 1, 'touch-key')); $this->assertEquals(true, self::$cache->touch('touch-key', 'touch-key')); - $this->assertEquals('touch data', self::$cache->load('touch-key', 60, 'touch-key')); + $this->assertEquals('touch data', self::$cache->load('touch-key', 1, 'touch-key')); $this->assertEquals(false, self::$cache->touch('missing-touch-key', 'missing-touch-key')); self::$cache->purge('touch-key'); diff --git a/tests/Cache/MemoryTest.php b/tests/Cache/MemoryTest.php index 6b99ffd117..b3e2a7683b 100644 --- a/tests/Cache/MemoryTest.php +++ b/tests/Cache/MemoryTest.php @@ -20,20 +20,4 @@ class MemoryTest extends Base self::$cache->save('test:file36', 'file36'); $this->assertEquals(4, self::$cache->getSize()); } - - public function testTouchExpiredEntry(): void - { - $adapter = new Memory(); - $cache = new Cache($adapter); - - $cache->save('expired-touch-key', 'expired data'); - /** @var array{time: int, data: string} $stored */ - $stored = $adapter->store['expired-touch-key']; - $stored['time'] = time() - 10; - $adapter->store['expired-touch-key'] = $stored; - - $this->assertEquals(false, $cache->load('expired-touch-key', 1)); - $this->assertEquals(true, $cache->touch('expired-touch-key')); - $this->assertEquals('expired data', $cache->load('expired-touch-key', 1)); - } } From 759794356e4b7c67cdb1653244d05a53a87adcde Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Fri, 8 May 2026 17:10:56 +0400 Subject: [PATCH 4/4] fix: stabilize filesystem touch test --- src/Cache/Adapter/Filesystem.php | 8 +++++++- tests/Cache/Base.php | 6 +++--- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/src/Cache/Adapter/Filesystem.php b/src/Cache/Adapter/Filesystem.php index 43fb5ed631..02c8649de9 100644 --- a/src/Cache/Adapter/Filesystem.php +++ b/src/Cache/Adapter/Filesystem.php @@ -106,7 +106,13 @@ class Filesystem implements Adapter { $file = $this->getPath($key); - return file_exists($file) && touch($file); + if (! file_exists($file) || ! touch($file)) { + return false; + } + + clearstatcache(true, $file); + + return true; } /** diff --git a/tests/Cache/Base.php b/tests/Cache/Base.php index d5f9f013ba..4fd13cb62e 100644 --- a/tests/Cache/Base.php +++ b/tests/Cache/Base.php @@ -62,11 +62,11 @@ abstract class Base extends TestCase $result = self::$cache->save('touch-key', 'touch data', 'touch-key'); $this->assertEquals('touch data', $result); - sleep(2); + sleep(3); - $this->assertEquals(false, self::$cache->load('touch-key', 1, 'touch-key')); + $this->assertEquals(false, self::$cache->load('touch-key', 2, 'touch-key')); $this->assertEquals(true, self::$cache->touch('touch-key', 'touch-key')); - $this->assertEquals('touch data', self::$cache->load('touch-key', 1, 'touch-key')); + $this->assertEquals('touch data', self::$cache->load('touch-key', 2, 'touch-key')); $this->assertEquals(false, self::$cache->touch('missing-touch-key', 'missing-touch-key')); self::$cache->purge('touch-key');