feat(cache): add Memcached lock store

memleakd · memleakd · commit 95ad08a97733 · 2026-05-02T18:38:47.000+02:00
- add CAS-backed Memcached lock store support
- expose Memcached locks through MemcachedHandler
- normalize unsupported runtime clients to LockException
- cover owner-aware release, refresh, expiry, force release, and reconnect
- document Memcached lock requirements and caveats

Signed-off-by: memleakd &lt;121398829+memleakd@users.noreply.github.com&gt;
diff --git a/system/Cache/Exceptions/CacheException.php b/system/Cache/Exceptions/CacheException.php
@@ -59,4 +59,14 @@ public static function forHandlerNotFound()
     {
         return new static(lang('Cache.handlerNotFound'));
     }
+
+    /**
+     * Thrown when the handler cannot provide a lock store.
+     *
+     * @return static
+     */
+    public static function forUnsupportedLockStore()
+    {
+        return new static(lang('Cache.unsupportedLockStore'));
+    }
 }
diff --git a/system/Cache/Handlers/MemcachedHandler.php b/system/Cache/Handlers/MemcachedHandler.php
@@ -13,6 +13,10 @@
 
 namespace CodeIgniter\Cache\Handlers;
 
+use CodeIgniter\Cache\Exceptions\CacheException;
+use CodeIgniter\Cache\LockStoreInterface;
+use CodeIgniter\Cache\LockStoreProviderInterface;
+use CodeIgniter\Cache\LockStores\MemcachedLockStore;
 use CodeIgniter\Exceptions\BadMethodCallException;
 use CodeIgniter\Exceptions\CriticalError;
 use CodeIgniter\I18n\Time;
@@ -26,7 +30,7 @@
  *
  * @see \CodeIgniter\Cache\Handlers\MemcachedHandlerTest
  */
-class MemcachedHandler extends BaseHandler
+class MemcachedHandler extends BaseHandler implements LockStoreProviderInterface
 {
     /**
      * The memcached object
@@ -35,6 +39,8 @@ class MemcachedHandler extends BaseHandler
      */
     protected $memcached;
 
+    private ?LockStoreInterface $lockStore = null;
+
     /**
      * Memcached Configuration
      *
@@ -62,6 +68,7 @@ public function initialize(): void
         try {
             if (class_exists(Memcached::class)) {
                 $this->memcached = new Memcached();
+                $this->lockStore = null;
 
                 if ($this->config['raw']) {
                     $this->memcached->setOption(Memcached::OPT_BINARY_PROTOCOL, true);
@@ -82,6 +89,7 @@ public function initialize(): void
                 }
             } elseif (class_exists(Memcache::class)) {
                 $this->memcached = new Memcache();
+                $this->lockStore = null;
 
                 if (! $this->memcached->connect($this->config['host'], $this->config['port'])) {
                     throw new CriticalError('Cache: Memcache connection failed.');
@@ -219,6 +227,15 @@ public function isSupported(): bool
         return extension_loaded('memcached') || extension_loaded('memcache');
     }
 
+    public function lockStore(): LockStoreInterface
+    {
+        if (! $this->memcached instanceof Memcached) {
+            throw CacheException::forUnsupportedLockStore();
+        }
+
+        return $this->lockStore ??= new MemcachedLockStore($this->memcached, $this->prefix);
+    }
+
     public function ping(): bool
     {
         $version = $this->memcached->getVersion();
diff --git a/system/Cache/LockStores/MemcachedLockStore.php b/system/Cache/LockStores/MemcachedLockStore.php
@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\Cache\LockStores;
+
+use CodeIgniter\Cache\Handlers\MemcachedHandler;
+use CodeIgniter\Cache\LockStoreInterface;
+use Memcached;
+
+class MemcachedLockStore implements LockStoreInterface
+{
+    private const RELEASE_TTL = 2;
+
+    public function __construct(
+        private readonly Memcached $memcached,
+        private readonly string $prefix = '',
+    ) {
+    }
+
+    public function acquireLock(string $key, string $owner, int $ttl): bool
+    {
+        $key = MemcachedHandler::validateKey($key, $this->prefix);
+
+        return $this->memcached->add($key, $owner, $ttl);
+    }
+
+    public function releaseLock(string $key, string $owner): bool
+    {
+        $key = MemcachedHandler::validateKey($key, $this->prefix);
+
+        [$value, $cas] = $this->getValueAndCas($key);
+
+        if ($value !== $owner || $cas === null) {
+            return false;
+        }
+
+        // Memcached has no atomic compare-and-delete command. CAS narrows the
+        // release race by first shortening only the current owner's value.
+        if (! $this->memcached->cas($cas, $key, $owner, self::RELEASE_TTL)) {
+            return false;
+        }
+
+        return $this->memcached->delete($key);
+    }
+
+    public function forceReleaseLock(string $key): bool
+    {
+        $key = MemcachedHandler::validateKey($key, $this->prefix);
+
+        if ($this->memcached->delete($key)) {
+            return true;
+        }
+
+        return $this->memcached->getResultCode() === Memcached::RES_NOTFOUND;
+    }
+
+    public function refreshLock(string $key, string $owner, int $ttl): bool
+    {
+        $key = MemcachedHandler::validateKey($key, $this->prefix);
+
+        [$value, $cas] = $this->getValueAndCas($key);
+
+        if ($value !== $owner || $cas === null) {
+            return false;
+        }
+
+        return $this->memcached->cas($cas, $key, $owner, $ttl);
+    }
+
+    public function getLockOwner(string $key): ?string
+    {
+        $key   = MemcachedHandler::validateKey($key, $this->prefix);
+        $owner = $this->memcached->get($key);
+
+        if ($this->memcached->getResultCode() !== Memcached::RES_SUCCESS) {
+            return null;
+        }
+
+        return is_string($owner) ? $owner : null;
+    }
+
+    /**
+     * @return array{0: mixed, 1: float|int|null}
+     */
+    private function getValueAndCas(string $key): array
+    {
+        $extended = $this->memcached->get($key, null, Memcached::GET_EXTENDED);
+
+        if (! is_array($extended) || ! array_key_exists('value', $extended) || ! array_key_exists('cas', $extended)) {
+            return [null, null];
+        }
+
+        return [$extended['value'], $extended['cas']];
+    }
+}
diff --git a/system/Language/en/Cache.php b/system/Language/en/Cache.php
@@ -13,9 +13,10 @@
 
 // Cache language settings
 return [
-    'unableToWrite'   => 'Cache unable to write to "{0}".',
-    'invalidHandler'  => 'Cache driver "{0}" is not a valid cache handler.',
-    'invalidHandlers' => 'Cache config must have an array of $validHandlers.',
-    'noBackup'        => 'Cache config must have a handler and backupHandler set.',
-    'handlerNotFound' => 'Cache config has an invalid handler or backup handler specified.',
+    'unableToWrite'        => 'Cache unable to write to "{0}".',
+    'invalidHandler'       => 'Cache driver "{0}" is not a valid cache handler.',
+    'invalidHandlers'      => 'Cache config must have an array of $validHandlers.',
+    'noBackup'             => 'Cache config must have a handler and backupHandler set.',
+    'handlerNotFound'      => 'Cache config has an invalid handler or backup handler specified.',
+    'unsupportedLockStore' => 'The cache handler cannot provide a lock store with the current runtime client.',
 ];
diff --git a/system/Lock/LockManager.php b/system/Lock/LockManager.php
@@ -14,6 +14,7 @@
 namespace CodeIgniter\Lock;
 
 use CodeIgniter\Cache\CacheInterface;
+use CodeIgniter\Cache\Exceptions\CacheException;
 use CodeIgniter\Cache\LockStoreInterface;
 use CodeIgniter\Cache\LockStoreProviderInterface;
 use CodeIgniter\Exceptions\InvalidArgumentException;
@@ -36,7 +37,11 @@ public function __construct(CacheInterface $cache)
             throw LockException::forUnsupportedStore($cache::class);
         }
 
-        $this->store = $cache->lockStore();
+        try {
+            $this->store = $cache->lockStore();
+        } catch (CacheException) {
+            throw LockException::forUnsupportedStore($cache::class);
+        }
     }
 
     public function create(string $name, int $ttl = 300, ?string $owner = null): LockInterface
diff --git a/tests/system/Cache/Handlers/MemcachedHandlerTest.php b/tests/system/Cache/Handlers/MemcachedHandlerTest.php
@@ -14,6 +14,8 @@
 namespace CodeIgniter\Cache\Handlers;
 
 use CodeIgniter\Cache\CacheFactory;
+use CodeIgniter\Cache\LockStoreInterface;
+use CodeIgniter\Cache\LockStoreProviderInterface;
 use CodeIgniter\CLI\CLI;
 use CodeIgniter\Exceptions\BadMethodCallException;
 use CodeIgniter\I18n\Time;
@@ -104,6 +106,53 @@ public function testSave(): void
         $this->assertTrue($this->handler->save(self::$key1, 'value'));
     }
 
+    public function testLockOperations(): void
+    {
+        $handler = $this->handler;
+
+        $this->assertInstanceOf(LockStoreProviderInterface::class, $handler);
+
+        $store = $handler->lockStore();
+
+        $this->assertInstanceOf(LockStoreInterface::class, $store);
+        $this->assertTrue($store->acquireLock(self::$key1, 'owner1', 60));
+        $this->assertFalse($store->acquireLock(self::$key1, 'owner2', 60));
+        $this->assertSame('owner1', $store->getLockOwner(self::$key1));
+        $this->assertFalse($store->releaseLock(self::$key1, 'owner2'));
+        $this->assertFalse($store->refreshLock(self::$key1, 'owner2', 120));
+        $this->assertTrue($store->refreshLock(self::$key1, 'owner1', 120));
+        $this->assertTrue($store->releaseLock(self::$key1, 'owner1'));
+        $this->assertNull($store->getLockOwner(self::$key1));
+        $this->assertTrue($store->acquireLock(self::$key1, 'owner1', 60));
+        $this->assertTrue($store->forceReleaseLock(self::$key1));
+        $this->assertNull($store->getLockOwner(self::$key1));
+        $this->assertTrue($store->forceReleaseLock(self::$key1));
+    }
+
+    /**
+     * This test waits for 2 seconds before reacquiring the lock.
+     *
+     * @timeLimit 2.5
+     */
+    public function testExpiredLockCanBeAcquiredByNewOwner(): void
+    {
+        $handler = $this->handler;
+
+        $this->assertInstanceOf(LockStoreProviderInterface::class, $handler);
+
+        $store = $handler->lockStore();
+
+        $this->assertTrue($store->acquireLock(self::$key1, 'owner1', 1));
+
+        CLI::wait(2);
+
+        $this->assertTrue($store->acquireLock(self::$key1, 'owner2', 60));
+        $this->assertSame('owner2', $store->getLockOwner(self::$key1));
+        $this->assertFalse($store->releaseLock(self::$key1, 'owner1'));
+        $this->assertFalse($store->refreshLock(self::$key1, 'owner1', 120));
+        $this->assertTrue($store->releaseLock(self::$key1, 'owner2'));
+    }
+
     public function testSavePermanent(): void
     {
         $this->assertTrue($this->handler->save(self::$key1, 'value', 0));
@@ -200,11 +249,18 @@ public function testPing(): void
 
     public function testReconnect(): void
     {
+        $handler = $this->handler;
+
+        $this->assertInstanceOf(LockStoreProviderInterface::class, $handler);
+
+        $lockStore = $handler->lockStore();
+
         $this->handler->save(self::$key1, 'value');
         $this->assertSame('value', $this->handler->get(self::$key1));
 
         $this->assertTrue($this->handler->reconnect());
 
         $this->assertSame('value', $this->handler->get(self::$key1));
+        $this->assertNotSame($lockStore, $handler->lockStore());
     }
 }
diff --git a/tests/system/Lock/LockTest.php b/tests/system/Lock/LockTest.php
@@ -14,6 +14,10 @@
 namespace CodeIgniter\Lock;
 
 use CodeIgniter\Cache\CacheFactory;
+use CodeIgniter\Cache\Exceptions\CacheException;
+use CodeIgniter\Cache\Handlers\DummyHandler;
+use CodeIgniter\Cache\LockStoreInterface;
+use CodeIgniter\Cache\LockStoreProviderInterface;
 use CodeIgniter\Exceptions\InvalidArgumentException;
 use CodeIgniter\I18n\Time;
 use CodeIgniter\Lock\Exceptions\LockException;
@@ -198,6 +202,21 @@ public function testUnsupportedCacheHandlerThrows(): void
         new LockManager(CacheFactory::getHandler($this->config, 'dummy'));
     }
 
+    public function testUnsupportedLockStoreProviderThrows(): void
+    {
+        $cache = new class () extends DummyHandler implements LockStoreProviderInterface {
+            public function lockStore(): LockStoreInterface
+            {
+                throw CacheException::forUnsupportedLockStore();
+            }
+        };
+
+        $this->expectException(LockException::class);
+        $this->expectExceptionMessage('does not support locks');
+
+        new LockManager($cache);
+    }
+
     private function lockFile(string $name): string
     {
         return rtrim($this->config->file['storePath'], '\\/') . '/lock_' . hash('xxh128', $name);
diff --git a/user_guide_src/source/changelogs/v4.8.0.rst b/user_guide_src/source/changelogs/v4.8.0.rst
@@ -225,7 +225,7 @@ Libraries
 
 - **Context**: This new feature allows you to easily set and retrieve normal or hidden contextual data for the current request. See :ref:`Context <context>` for details.
 - **Images:**: Added support for the AVIF file format.
-- **Locks:** Added :doc:`Atomic Locks </libraries/locks>` for owner-aware, cross-process mutual exclusion backed by supported cache handlers.
+- **Locks:** Added :doc:`Atomic Locks </libraries/locks>` for owner-aware, cross-process mutual exclusion backed by supported cache handlers: **File**, **Redis**, **Predis**, and **Memcached**.
 - **Logging:** Log handlers now receive the full context array as a third argument to ``handle()``. When ``$logGlobalContext`` is enabled, the CI global context is available under the ``HandlerInterface::GLOBAL_CONTEXT_KEY`` key. Built-in handlers append it to the log output; custom handlers can use it for structured logging.
 - **Logging:** Added :ref:`per-call context logging <logging-per-call-context>` with three new ``Config\Logger`` options (``$logContext``, ``$logContextTrace``, ``$logContextUsedKeys``). Per PSR-3, a ``Throwable`` in the ``exception`` context key is automatically normalized to a meaningful array. All options default to ``false``.
 
diff --git a/user_guide_src/source/libraries/locks.rst b/user_guide_src/source/libraries/locks.rst
@@ -20,8 +20,8 @@ Configuration
 *************
 
 The Locks library uses the Cache service. The cache handler must support atomic
-lock operations. The built-in **File**, **Redis**, and **Predis** cache handlers
-support locks.
+lock operations. The built-in **File**, **Redis**, **Predis**, and
+**Memcached** cache handlers support locks.
 
 .. note:: Locks are most useful when all competing processes share the same cache
     storage. The File handler is suitable for a single server. For multiple
@@ -33,6 +33,11 @@ support locks.
     storage while lock-protected work is running, or use a dedicated cache
     store for locks when that separation is important.
 
+.. note:: Memcached lock support requires the ``memcached`` PHP extension.
+    The older ``memcache`` extension does not provide the CAS operations needed
+    for owner-aware release and refresh. Memcached locks may also be lost if the
+    Memcached server restarts, evicts keys, or flushes its cache.
+
 .. note:: File-backed locks clear released and expired lock contents, but may
     leave empty lock files in the cache directory. These files do not represent
     active locks and may be removed by normal cache cleanup when no

Original file line number	Diff line number	Diff line change
`@@ -59,4 +59,14 @@ public static function forHandlerNotFound()`
`59`	`59`	`{`
`60`	`60`	`return new static(lang('Cache.handlerNotFound'));`
`61`	`61`	`}`
	`62`	`+`
	`63`	`+ /**`
	`64`	`+ * Thrown when the handler cannot provide a lock store.`
	`65`	`+ *`
	`66`	`+ * @return static`
	`67`	`+ */`
	`68`	`+ public static function forUnsupportedLockStore()`
	`69`	`+ {`
	`70`	`+ return new static(lang('Cache.unsupportedLockStore'));`
	`71`	`+ }`
`62`	`72`	`}`