Added cache backends registry.

VERSION

@@ -1 +1 @@
-0.2410.160124
+0.2410.182054

composer.json

@@ -34,6 +34,9 @@
             "Index\\": "src"
         },
         "files": [
+            "src/Cache/ArrayCache/_ndx.php",
+            "src/Cache/Memcached/_ndx.php",
+            "src/Cache/Valkey/_ndx.php",
             "src/Db/MariaDb/_ndx.php",
             "src/Db/NullDb/_ndx.php",
             "src/Db/Sqlite/_ndx.php"

composer.lock

@@ -943,16 +943,16 @@
         },
         {
             "name": "phpstan/phpstan",
-            "version": "1.12.6",
+            "version": "1.12.7",
             "source": {
                 "type": "git",
                 "url": "https://github.com/phpstan/phpstan.git",
-                "reference": "dc4d2f145a88ea7141ae698effd64d9df46527ae"
+                "reference": "dc2b9976bd8b0f84ec9b0e50cc35378551de7af0"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/phpstan/phpstan/zipball/dc4d2f145a88ea7141ae698effd64d9df46527ae",
-                "reference": "dc4d2f145a88ea7141ae698effd64d9df46527ae",
+                "url": "https://api.github.com/repos/phpstan/phpstan/zipball/dc2b9976bd8b0f84ec9b0e50cc35378551de7af0",
+                "reference": "dc2b9976bd8b0f84ec9b0e50cc35378551de7af0",
                 "shasum": ""
             },
             "require": {
@@ -997,7 +997,7 @@
                     "type": "github"
                 }
             ],
-            "time": "2024-10-06T15:03:59+00:00"
+            "time": "2024-10-18T11:12:07+00:00"
         },
         {
             "name": "phpunit/php-code-coverage",
@@ -1594,16 +1594,16 @@
         },
         {
             "name": "sebastian/comparator",
-            "version": "6.1.0",
+            "version": "6.1.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/sebastianbergmann/comparator.git",
-                "reference": "fa37b9e2ca618cb051d71b60120952ee8ca8b03d"
+                "reference": "5ef523a49ae7a302b87b2102b72b1eda8918d686"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/fa37b9e2ca618cb051d71b60120952ee8ca8b03d",
-                "reference": "fa37b9e2ca618cb051d71b60120952ee8ca8b03d",
+                "url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/5ef523a49ae7a302b87b2102b72b1eda8918d686",
+                "reference": "5ef523a49ae7a302b87b2102b72b1eda8918d686",
                 "shasum": ""
             },
             "require": {
@@ -1659,7 +1659,7 @@
             "support": {
                 "issues": "https://github.com/sebastianbergmann/comparator/issues",
                 "security": "https://github.com/sebastianbergmann/comparator/security/policy",
-                "source": "https://github.com/sebastianbergmann/comparator/tree/6.1.0"
+                "source": "https://github.com/sebastianbergmann/comparator/tree/6.1.1"
             },
             "funding": [
                 {
@@ -1667,7 +1667,7 @@
                     "type": "github"
                 }
             ],
-            "time": "2024-09-11T15:42:56+00:00"
+            "time": "2024-10-18T15:00:48+00:00"
         },
         {
             "name": "sebastian/complexity",

src/Cache/ArrayCache/_ndx.php

@@ -0,0 +1,11 @@
+<?php
+// _ndx.php
+// Created: 2024-10-18
+// Updated: 2024-10-18
+
+namespace Index\Cache\ArrayCache;
+
+use Index\Cache\CacheBackends;
+
+CacheBackends::register('array', ArrayCacheBackend::class);
+CacheBackends::register('null', ArrayCacheBackend::class);

src/Cache/CacheBackends.php

@@ -0,0 +1,108 @@
+<?php
+// CacheBackends.php
+// Created: 2024-10-18
+// Updated: 2024-10-18
+
+namespace Index\Cache;
+
+use InvalidArgumentException;
+use RuntimeException;
+
+/**
+ * Provides a registry of cache backends.
+ */
+final class CacheBackends {
+    /** @var array<string, string> */
+    private static array $schemes = [];
+
+    /** @var array<string, CacheBackend> */
+    private static array $backends = [];
+
+    /**
+     * @throws RuntimeException Will always throw because this is a static class exclusively.
+     */
+    public function __construct() {
+        throw new RuntimeException('This is a static class, you cannot create an instance of it.');
+    }
+
+    /**
+     * Registers a cache backend with a protocol scheme.
+     *
+     * @param string $scheme URL scheme.
+     * @param string $className Fully qualified class name of the backend.
+     * @throws InvalidArgumentException If $scheme is already registered.
+     */
+    public static function register(string $scheme, string $className): void {
+        $scheme = strtolower($scheme);
+        if(array_key_exists($scheme, self::$schemes))
+            throw new InvalidArgumentException('$scheme has already been registered');
+
+        self::$schemes[$scheme] = $className;
+    }
+
+    /**
+     * Creates a cache provider from a DSN URI.
+     *
+     * @param string $uri DSN URI.
+     * @throws RuntimeException If the requested cache backend is not available.
+     * @return CacheProvider Connection instance.
+     */
+    public static function create(string $uri): CacheProvider {
+        $parsed = self::parseUri($uri);
+
+        $backend = self::backend($parsed['scheme']);
+        if(!$backend->isAvailable())
+            throw new RuntimeException('requested cache backend is not available');
+
+        return $backend->createProvider($backend->parseDsn($parsed));
+    }
+
+    /**
+     * Parses a DSN URI into a provider info class.
+     *
+     * @param string $uri DSN URI.
+     * @return CacheProviderInfo Provider info instance.
+     */
+    public static function parse(string $uri): CacheProviderInfo {
+        $parsed = self::parseUri($uri);
+        return self::backend($parsed['scheme'])->parseDsn($parsed);
+    }
+
+    /**
+     * Creates a cache provider information class from a scheme.
+     *
+     * @param string $scheme Cache protocol scheme.
+     * @throws InvalidArgumentException If $scheme is not a registered protocol scheme.
+     * @throws RuntimeException If the implementation class is not available or doesn't implement CacheBackend.
+     * @return CacheBackend Cache backend information instance.
+     */
+    public static function backend(string $scheme): CacheBackend {
+        $scheme = strtolower($scheme);
+        if(!array_key_exists($scheme, self::$schemes))
+            throw new InvalidArgumentException('$scheme is not a registered scheme');
+
+        $className = self::$schemes[$scheme];
+        if(array_key_exists($className, self::$backends))
+            return self::$backends[$className];
+
+        if(!class_exists($className))
+            throw new RuntimeException('implementation class for the given $scheme does not exist');
+
+        $backend = new $className;
+        if(!($backend instanceof CacheBackend))
+            throw new RuntimeException('implementation class for the given $scheme does not implement CacheBackend');
+
+        self::$backends[$className] = $backend;
+        return $backend;
+    }
+
+    /** @return array{scheme: string, host?: string, port?: int, user?: string, pass?: string, path?: string, query?: string, fragment?: string} */
+    private static function parseUri(string $uri): array {
+        $uri = parse_url($uri);
+        if($uri === false)
+            throw new InvalidArgumentException('$uri is not a valid uri');
+        if(empty($uri['scheme']))
+            throw new InvalidArgumentException('$uri must contain a non-empty scheme component');
+        return $uri;
+    }
+}

src/Cache/CacheTools.php

@@ -1,112 +0,0 @@
-<?php
-// CacheTools.php
-// Created: 2024-04-10
-// Updated: 2024-10-16
-
-namespace Index\Cache;
-
-use InvalidArgumentException;
-use RuntimeException;
-
-/**
- * Common cache actions.
- *
- * DSN documentation:
- *
- * CacheTools only handles the scheme part of the URL,
- *  the rest of the URL is described in the documentation of the parseDsn implementation of the respective backend.
- *
- * The scheme can be a PHP classpath to an implementation of CacheBackend, or any of these aliases:
- *  - `array`, `null`: maps to `ArrayCache\ArrayCacheBackend`, uses a simple array backed cache that doesn't get saved.
- *  - `memcached`, `memcache`: maps to `Memcached\MemcachedBackend`, provides a backend based on the memcached or memcache extension.
- *  - `valkey`, `keydb`, `redis`: maps to `Valkey\ValkeyBackend`, provides a backend based on the phpredis extension.
- *
- * Short names are currently hardcoded and cannot be expanded.
- */
-final class CacheTools {
-    private const CACHE_PROTOS = [
-        'array' => ArrayCache\ArrayCacheBackend::class,
-        'null' => ArrayCache\ArrayCacheBackend::class,
-        'memcached' => Memcached\MemcachedBackend::class,
-        'memcache' => Memcached\MemcachedBackend::class,
-        'valkey' => Valkey\ValkeyBackend::class,
-        'redis' => Valkey\ValkeyBackend::class,
-        'keydb' => Valkey\ValkeyBackend::class,
-    ];
-
-    /** @return array<string, int|string> */
-    private static function parseDsnUri(string $dsn): array {
-        $uri = parse_url($dsn);
-        if($uri === false)
-            throw new InvalidArgumentException('$dsn is not a valid uri.');
-        return $uri;
-    }
-
-    /** @param array<string, int|string> $uri */
-    private static function resolveBackend(array $uri): CacheBackend {
-        static $backends = null;
-        if(!is_array($backends))
-            $backends = [];
-
-        $scheme = $uri['scheme'];
-        $backend = $backends[$scheme] ?? null;
-
-        if(!($backend instanceof CacheBackend)) {
-            if(!array_key_exists($scheme, self::CACHE_PROTOS))
-                throw new RuntimeException('No implementation is available for the specified scheme.');
-
-            $backend = new (self::CACHE_PROTOS[$scheme]);
-            if(!$backend->isAvailable())
-                throw new RuntimeException('Requested cache backend is not available, likely due to missing dependencies.');
-
-            $backends[$scheme] = $backend;
-        }
-
-        return $backend;
-    }
-
-    /**
-     * Retrieves cache provider based on DSN URL.
-     *
-     * Format of the DSN URLs are described in the documentation of the CacheTools class as a whole.
-     *
-     * @param string $dsn URL to create cache provider from.
-     * @throws InvalidArgumentException if $dsn is not a valid URL.
-     * @throws RuntimeException if no cache provider can be made using the URL.
-     * @return CacheBackend Cache backend instance.
-     */
-    public static function backend(string $dsn): CacheBackend {
-        return self::resolveBackend(self::parseDsnUri($dsn));
-    }
-
-    /**
-     * Parses a DSN URL.
-     *
-     * Format of the DSN URLs are described in the documentation of the CacheTools class as a whole.
-     *
-     * @param string $dsn URL to create cache provider from.
-     * @throws InvalidArgumentException if $dsn is not a valid URL.
-     * @throws RuntimeException if no cache provider can be made using the URL.
-     * @return CacheProviderInfo Cache provider info.
-     */
-    public static function parse(string $dsn): CacheProviderInfo {
-        $uri = self::parseDsnUri($dsn);
-        return self::resolveBackend($uri)->parseDsn($uri);
-    }
-
-    /**
-     * Uses a DSN URL to create a cache provider instance.
-     *
-     * Format of the DSN URLs are described in the documentation of the CacheTools class as a whole.
-     *
-     * @param string $dsn URL to create cache provider from.
-     * @throws InvalidArgumentException if $dsn is not a valid URL.
-     * @throws RuntimeException if no cache provider can be made using the URL.
-     * @return CacheProvider A cache provider.
-     */
-    public static function create(string $dsn): CacheProvider {
-        $uri = self::parseDsnUri($dsn);
-        $backend = self::resolveBackend($uri);
-        return $backend->createProvider($backend->parseDsn($uri));
-    }
-}

src/Cache/Memcached/_ndx.php

@@ -0,0 +1,11 @@
+<?php
+// _ndx.php
+// Created: 2024-10-18
+// Updated: 2024-10-18
+
+namespace Index\Cache\Memcached;
+
+use Index\Cache\CacheBackends;
+
+CacheBackends::register('memcached', MemcachedBackend::class);
+CacheBackends::register('memcache', MemcachedBackend::class);

src/Cache/Valkey/_ndx.php

@@ -0,0 +1,12 @@
+<?php
+// _ndx.php
+// Created: 2024-10-18
+// Updated: 2024-10-18
+
+namespace Index\Cache\Valkey;
+
+use Index\Cache\CacheBackends;
+
+CacheBackends::register('valkey', ValkeyBackend::class);
+CacheBackends::register('redis', ValkeyBackend::class);
+CacheBackends::register('keydb', ValkeyBackend::class);

src/Db/DbBackends.php

@@ -1,4 +1,8 @@
 <?php
+// DbBackends.php
+// Created: 2024-10-18
+// Updated: 2024-10-18
+
 namespace Index\Db;
 
 use InvalidArgumentException;
@@ -25,7 +29,7 @@ final class DbBackends {
      * Registers a database backend with a protocol scheme.
      *
      * @param string $scheme URL scheme.
-     * @param string $className Fully qualified class name of backend.
+     * @param string $className Fully qualified class name of the backend.
      * @throws InvalidArgumentException If $scheme is already registered.
      */
     public static function register(string $scheme, string $className): void {

src/Db/MariaDb/_ndx.php

@@ -1,4 +1,8 @@
 <?php
+// _ndx.php
+// Created: 2024-10-18
+// Updated: 2024-10-18
+
 namespace Index\Db\MariaDb;
 
 use Index\Db\DbBackends;

src/Db/NullDb/_ndx.php

@@ -1,4 +1,8 @@
 <?php
+// _ndx.php
+// Created: 2024-10-18
+// Updated: 2024-10-18
+
 namespace Index\Db\NullDb;
 
 use Index\Db\DbBackends;

src/Db/Sqlite/_ndx.php

@@ -1,4 +1,8 @@
 <?php
+// _ndx.php
+// Created: 2024-10-18
+// Updated: 2024-10-18
+
 namespace Index\Db\Sqlite;
 
 use Index\Db\DbBackends;

tests/CacheBackendsTest.php

@@ -1,19 +1,19 @@
 <?php
-// CacheToolsTest.php
+// CacheBackendsTest.php
 // Created: 2024-04-10
-// Updated: 2024-10-16
+// Updated: 2024-10-18
 
 declare(strict_types=1);
 
 use PHPUnit\Framework\TestCase;
 use PHPUnit\Framework\Attributes\{CoversClass,UsesClass};
-use Index\Cache\CacheTools;
+use Index\Cache\CacheBackends;
 use Index\Cache\ArrayCache\{ArrayCacheBackend,ArrayCacheProvider};
 use Index\Cache\Memcached\MemcachedBackend;
 use Index\Cache\Valkey\ValkeyBackend;
 use Index\Net\{DnsEndPoint,IpEndPoint,UnixEndPoint};
 
-#[CoversClass(CacheTools::class)]
+#[CoversClass(CacheBackends::class)]
 #[CoversClass(ArrayCacheBackend::class)]
 #[CoversClass(ArrayCacheProvider::class)]
 #[CoversClass(MemcachedBackend::class)]
@@ -21,9 +21,9 @@ use Index\Net\{DnsEndPoint,IpEndPoint,UnixEndPoint};
 #[UsesClass(DnsEndPoint::class)]
 #[UsesClass(IpEndPoint::class)]
 #[UsesClass(UnixEndPoint::class)]
-final class CacheToolsTest extends TestCase {
+final class CacheBackendsTest extends TestCase {
     public function testBasicDSN(): void {
-        $arrayCache = CacheTools::create('array:');
+        $arrayCache = CacheBackends::create('array:');
         $this->assertInstanceOf(ArrayCacheProvider::class, $arrayCache);
     }
 

tests/DbBackendsTest.php

@@ -1,5 +1,5 @@
 <?php
-// DbToolsTest.php
+// DbBackendsTest.php
 // Created: 2021-04-28
 // Updated: 2024-10-16