feat: APCu caching driver

.github/workflows/reusable-phpunit-test.yml

@@ -43,6 +43,10 @@ on:
         description: Additional PHP extensions that are needed to be enabled
         type: string
         required: false
+      extra-ini-options:
+        description: Additional PHP configuration directives that should be appended to the php.ini
+        type: string
+        required: false
       extra-composer-options:
         description: Additional Composer options that should be appended to the `composer update` call
         type: string
@@ -163,6 +167,7 @@ jobs:
           php-version: ${{ inputs.php-version }}
           tools: composer
           extensions: gd, ${{ inputs.extra-extensions }}
+          ini-values: ${{ inputs.extra-ini-options }}
           coverage: ${{ env.COVERAGE_DRIVER }}
         env:
           COVERAGE_DRIVER: ${{ inputs.enable-coverage && 'xdebug' || 'none' }}

.github/workflows/test-phpunit.yml

@@ -163,7 +163,8 @@ jobs:
       enable-artifact-upload: ${{ matrix.php-version == needs.coverage-php-version.outputs.version }}
       enable-coverage: ${{ matrix.php-version == needs.coverage-php-version.outputs.version }}
       enable-profiling: ${{ matrix.php-version == needs.coverage-php-version.outputs.version }}
-      extra-extensions: redis, memcached
+      extra-extensions: redis, memcached, apcu
+      extra-ini-options: apc.enable_cli=1
       extra-composer-options: ${{ matrix.composer-option }}
 
   coveralls:

admin/framework/composer.json

@@ -27,6 +27,7 @@
         "predis/predis": "^3.0"
     },
     "suggest": {
+        "ext-apcu": "If you use Cache class ApcuHandler",
         "ext-curl": "If you use CURLRequest class",
         "ext-dom": "If you use TestResponse",
         "ext-exif": "If you run Image class tests",

app/Config/Cache.php

@@ -3,6 +3,7 @@
 namespace Config;
 
 use CodeIgniter\Cache\CacheInterface;
+use CodeIgniter\Cache\Handlers\ApcuHandler;
 use CodeIgniter\Cache\Handlers\DummyHandler;
 use CodeIgniter\Cache\Handlers\FileHandler;
 use CodeIgniter\Cache\Handlers\MemcachedHandler;
@@ -143,6 +144,7 @@ class Cache extends BaseConfig
      * @var array<string, class-string<CacheInterface>>
      */
     public array $validHandlers = [
+        'apcu'      => ApcuHandler::class,
         'dummy'     => DummyHandler::class,
         'file'      => FileHandler::class,
         'memcached' => MemcachedHandler::class,

composer.json

@@ -35,6 +35,7 @@
         "codeigniter4/framework": "self.version"
     },
     "suggest": {
+        "ext-apcu": "If you use Cache class ApcuHandler",
         "ext-curl": "If you use CURLRequest class",
         "ext-dom": "If you use TestResponse",
         "ext-exif": "If you run Image class tests",

system/Cache/Handlers/ApcuHandler.php

@@ -0,0 +1,163 @@
+<?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\Handlers;
+
+use APCUIterator;
+use Closure;
+use CodeIgniter\I18n\Time;
+use Config\Cache;
+
+/**
+ * APCu cache handler
+ *
+ * @see \CodeIgniter\Cache\Handlers\ApcuHandlerTest
+ */
+class ApcuHandler extends BaseHandler
+{
+    /**
+     * Note: Use `CacheFactory::getHandler()` to instantiate.
+     */
+    public function __construct(Cache $config)
+    {
+        $this->prefix = $config->prefix;
+    }
+
+    public function initialize(): void
+    {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function get(string $key): mixed
+    {
+        $key     = static::validateKey($key, $this->prefix);
+        $success = false;
+
+        $data = apcu_fetch($key, $success);
+
+        // Success returned by reference from apcu_fetch()
+        return $success ? $data : null;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function save(string $key, $value, int $ttl = 60): bool
+    {
+        $key = static::validateKey($key, $this->prefix);
+
+        return apcu_store($key, $value, $ttl);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function remember(string $key, int $ttl, Closure $callback): mixed
+    {
+        $key = static::validateKey($key, $this->prefix);
+
+        return apcu_entry($key, $callback, $ttl);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function delete(string $key): bool
+    {
+        $key = static::validateKey($key, $this->prefix);
+
+        return apcu_delete($key);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function deleteMatching(string $pattern): int
+    {
+        $matchedKeys = array_filter(
+            array_keys(iterator_to_array(new APCUIterator(null, APC_ITER_KEY))),
+            static fn ($key): bool => fnmatch($pattern, $key),
+        );
+
+        if ($matchedKeys !== []) {
+            return count($matchedKeys) - count(apcu_delete($matchedKeys));
+        }
+
+        return 0;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function increment(string $key, int $offset = 1): false|int
+    {
+        $key = static::validateKey($key, $this->prefix);
+
+        return apcu_inc($key, $offset);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function decrement(string $key, int $offset = 1): false|int
+    {
+        $key = static::validateKey($key, $this->prefix);
+
+        return apcu_dec($key, $offset);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function clean(): bool
+    {
+        return apcu_clear_cache();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getCacheInfo(): array|false
+    {
+        return apcu_cache_info(true);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getMetaData(string $key): ?array
+    {
+        $key      = static::validateKey($key, $this->prefix);
+        $metadata = apcu_key_info($key);
+
+        if ($metadata !== null) {
+            return [
+                'expire' => $metadata['ttl'] > 0 ? Time::now()->getTimestamp() + $metadata['ttl'] : null,
+                'mtime'  => $metadata['mtime'],
+                'data'   => apcu_fetch($key),
+            ];
+        }
+
+        return null;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function isSupported(): bool
+    {
+        return extension_loaded('apcu') && apcu_enabled();
+    }
+}