Feature/update 26

README.md

@@ -5,7 +5,7 @@ CacheLayer is a standalone cache toolkit for modern PHP applications.
 It provides:
 
 - PSR-6 and PSR-16 compatible `Cache` facade
-- Adapters for `APCu`, `File`, `Memcached`, `Redis`, `Redis Cluster`, `SQLite`, `PostgreSQL`
+- Adapters for `APCu`, `File`, `Memcached`, `Redis`, `Redis Cluster`, `PDO (default SQLite; also MySQL/MariaDB/PostgreSQL/etc.)`
 - In-process adapters: `memory` (array), `weakMap`, `nullStore`, `chain`
 - Filesystem/Opcode adapter: `phpFiles`
 - Shared-memory adapter: `sharedMemory` (sysvshm)
@@ -40,8 +40,9 @@ Cache::phpFiles('ns', __DIR__ . '/storage/cache');
 Cache::memcache('ns');
 Cache::redis('ns');
 Cache::redisCluster('ns', ['127.0.0.1:6379']);
+Cache::pdo('ns'); // defaults to sqlite file in sys temp dir
 Cache::sqlite('ns');
-Cache::postgres('ns');
+Cache::pdo('ns', 'mysql:host=127.0.0.1;port=3306;dbname=app', 'user', 'pass');
 Cache::memory('ns');
 Cache::weakMap('ns');
 Cache::sharedMemory('ns');

composer.json

@@ -13,6 +13,9 @@
         "redis",
         "memcached",
         "sqlite",
+        "pdo",
+        "mysql",
+        "mariadb",
         "postgres",
         "mongodb",
         "dynamodb",
@@ -30,9 +33,10 @@
         "ext-apcu": "For APCu-based caching (in-memory, per-process)",
         "ext-redis": "For Redis-based caching (persistent, networked)",
         "ext-memcached": "For Memcached-based caching (distributed, RAM)",
-        "ext-sqlite3": "For SQLite-based caching (file-based, portable)",
-        "ext-pdo": "For SQLite-based caching (file-based, portable)",
-        "ext-pdo_pgsql": "For PostgreSQL-based caching via PostgresCacheAdapter",
+        "ext-pdo": "For PDO-based SQL caching (MySQL/MariaDB/PostgreSQL/etc.)",
+        "ext-pdo_sqlite": "For default SQLite usage via Cache::pdo(...) or Cache::sqlite(...)",
+        "ext-pdo_pgsql": "For PostgreSQL usage via Cache::pdo(...)",
+        "ext-pdo_mysql": "For MySQL/MariaDB usage via Cache::pdo(...)",
         "ext-sysvshm": "For shared-memory caching via SharedMemoryCacheAdapter",
         "mongodb/mongodb": "For MongoDB caching via MongoDbCacheAdapter",
         "aws/aws-sdk-php": "For DynamoDB and S3 adapters",

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/theme.css

@@ -0,0 +1,3 @@
+.highlight-php .k {
+  color: #0077aa; /* Example: make PHP keywords a different color */
+}

docs/adapters/apcu.rst

@@ -0,0 +1,21 @@
+.. _adapters.apcu:
+
+=======================
+APCu Adapter (`apcu`)
+=======================
+
+Factory: `Cache::apcu(string $namespace = 'default')`
+
+Requirements:
+
+* `ext-apcu`
+* APCu enabled (`apcu_enabled()`)
+* for CLI usage/tests: `apcu.enable_cli=1`
+
+Highlights:
+
+* in-memory shared cache in the PHP runtime environment
+* namespace-prefixed keys (`<ns>:<key>`)
+* efficient bulk fetch through APCu array fetch path
+
+`Cache::local()` will choose APCu automatically when available.

docs/adapters/array-memory.rst

@@ -0,0 +1,23 @@
+.. _adapters.array_memory:
+
+============================
+Array Adapter (`memory`)
+============================
+
+Factory: `Cache::memory(string $namespace = 'default')`
+
+In-process array-backed adapter for fast ephemeral caching.
+
+Characteristics:
+
+* no external dependencies
+* not shared across processes
+* TTL support via encoded expiration timestamps
+* suitable for tests and simple local memo/cache layers
+
+Example:
+
+.. code-block:: php
+
+   $cache = Cache::memory('local');
+   $cache->set('foo', 'bar', 10);

docs/adapters/chain.rst

@@ -0,0 +1,32 @@
+.. _adapters.chain:
+
+=========================
+Chain Adapter (`chain`)
+=========================
+
+Factory: `Cache::chain(array $pools)`
+
+Composes multiple PSR-6 pools into a tiered cache.
+
+Behavior:
+
+* writes are propagated to all tiers
+* reads search from first tier to last tier
+* hit in lower tier is promoted upward
+
+Typical layout:
+
+* L1: in-memory (`ArrayCacheAdapter`)
+* L2: network cache (`RedisCacheAdapter`)
+
+Example:
+
+.. code-block:: php
+
+   use Infocyph\CacheLayer\Cache\Adapter\ArrayCacheAdapter;
+   use Infocyph\CacheLayer\Cache\Adapter\RedisCacheAdapter;
+
+   $cache = Cache::chain([
+       new ArrayCacheAdapter('l1'),
+       new RedisCacheAdapter('l2'),
+   ]);

docs/adapters/dynamodb.rst

@@ -0,0 +1,28 @@
+.. _adapters.dynamodb:
+
+================================
+DynamoDB Adapter (`dynamoDb`)
+================================
+
+Factory:
+
+`Cache::dynamoDb(string $namespace = 'default', string $table = 'cachelayer_entries', ?object $client = null, array $config = [])`
+
+Requirements:
+
+* `aws/aws-sdk-php` for default client path, or
+* injected client implementing required DynamoDB methods
+
+Highlights:
+
+* namespace-scoped row storage
+* clear via scan + chunked `batchWriteItem` delete requests
+* TTL stored as absolute timestamp in `expires`
+
+Supported injected client methods:
+
+* `getItem`
+* `putItem`
+* `deleteItem`
+* `scan`
+* `batchWriteItem`

docs/adapters/file.rst

@@ -0,0 +1,24 @@
+.. _adapters.file:
+
+=======================
+File Adapter (`file`)
+=======================
+
+Factory: `Cache::file(string $namespace = 'default', ?string $dir = null)`
+
+Stores one cache payload per file under a namespace directory.
+
+Path layout:
+
+* base dir: provided `$dir` or `sys_get_temp_dir()`
+* namespace dir: `cache_<sanitized-namespace>`
+* file name: `hash('xxh128', $key) . '.cache'`
+
+Highlights:
+
+* zero service dependencies
+* persists across process restarts
+* atomic write flow (`tempnam` + `rename`)
+* `setNamespaceAndDirectory()` supported
+
+Best for local/single-host environments.

docs/adapters/index.rst

@@ -0,0 +1,29 @@
+.. _adapters:
+
+===================
+Cache Adapters
+===================
+
+CacheLayer ships multiple adapters for different runtime and infrastructure
+needs.
+
+.. toctree::
+   :maxdepth: 1
+
+   array-memory
+   weak-map
+   null-store
+   chain
+   file
+   php-files
+   apcu
+   memcached
+   redis
+   redis-cluster
+   sqlite
+   pdo
+   shared-memory
+   mongodb
+   dynamodb
+   s3
+   serialization

docs/adapters/memcached.rst

@@ -0,0 +1,22 @@
+.. _adapters.memcached:
+
+=================================
+Memcached Adapter (`memcache`)
+=================================
+
+Factory:
+
+`Cache::memcache(string $namespace = 'default', array $servers = [['127.0.0.1', 11211, 0]], ?Memcached $client = null)`
+
+Requirements:
+
+* `ext-memcached`
+* reachable Memcached server(s)
+
+Highlights:
+
+* distributed in-memory cache
+* `getMulti` based batch reads
+* factory auto-configures `MemcachedLockProvider` for `remember()` when using this adapter
+
+You may pass your own preconfigured `Memcached` client.

docs/adapters/mongodb.rst

@@ -0,0 +1,29 @@
+.. _adapters.mongodb:
+
+=============================
+MongoDB Adapter (`mongodb`)
+=============================
+
+Factories:
+
+* `Cache::mongodb(...)`
+* `MongoDbCacheAdapter::fromClient(...)` (adapter-level)
+
+Requirements:
+
+* `mongodb/mongodb` package for default client path, or
+* injected collection/client compatible with expected methods
+
+Highlights:
+
+* namespace-scoped document storage
+* base64-encoded payload persistence
+* TTL-aware read-time pruning
+
+Supported injected collection methods:
+
+* `findOne`
+* `updateOne`
+* `deleteOne`
+* `deleteMany`
+* `countDocuments`

docs/adapters/null-store.rst

@@ -0,0 +1,17 @@
+.. _adapters.null_store:
+
+============================
+Null Adapter (`nullStore`)
+============================
+
+Factory: `Cache::nullStore()`
+
+No-op adapter that never persists values.
+
+Behavior:
+
+* `set()` returns true
+* `get()` always misses unless default/callable path is used
+* `remember()` recomputes every call
+
+Useful for disabling caching without changing calling code.

docs/adapters/pdo.rst

@@ -0,0 +1,49 @@
+.. _adapters.pdo:
+
+=========================
+PDO Adapter (`pdo`)
+=========================
+
+Factory:
+
+`Cache::pdo(string $namespace = 'default', ?string $dsn = null, ?string $username = null, ?string $password = null, ?PDO $pdo = null, string $table = 'cachelayer_entries')`
+
+Requirements:
+
+* `ext-pdo`
+* the target PDO driver for your DSN (`pdo_mysql`, `pdo_pgsql`, etc.)
+
+Highlights:
+
+* unified SQL adapter for MySQL, MariaDB, PostgreSQL, and other PDO drivers
+* defaults to SQLite when no DSN/PDO is provided
+* namespace-prefixed row keys (`<ns>:<key>`)
+* automatic table/index initialization
+* driver-aware upsert strategy:
+  - PostgreSQL/SQLite: native `ON CONFLICT`
+  - MySQL/MariaDB: native `ON DUPLICATE KEY UPDATE`
+  - fallback path for other PDO drivers
+* batched `multiFetch()` via single `IN (...)` query
+
+Examples:
+
+.. code-block:: php
+
+   // Default sqlite file under sys temp dir
+   $cacheDefault = Cache::pdo('app');
+
+   // MySQL / MariaDB
+   $cache = Cache::pdo(
+       'app',
+       'mysql:host=127.0.0.1;port=3306;dbname=app',
+       'user',
+       'pass',
+   );
+
+   // PostgreSQL
+   $cachePg = Cache::pdo(
+       'app',
+       'pgsql:host=127.0.0.1;port=5432;dbname=app',
+       'postgres',
+       'postgres',
+   );

docs/adapters/php-files.rst

@@ -0,0 +1,23 @@
+.. _adapters.php_files:
+
+==============================
+PHP Files Adapter (`phpFiles`)
+==============================
+
+Factory: `Cache::phpFiles(string $namespace = 'default', ?string $dir = null)`
+
+Persists cache records as PHP files that return payload arrays.
+
+Path layout:
+
+* base dir: provided `$dir` or `sys_get_temp_dir()`
+* namespace dir: `phpcache_<sanitized-namespace>`
+* file name: `hash('xxh128', $key) . '.php'`
+
+Highlights:
+
+* persistent local cache
+* opcode-cache aware (`opcache_invalidate` on writes/deletes when available)
+* `setNamespaceAndDirectory()` supported
+
+Good for environments where opcode cache integration is desired.

docs/adapters/redis-cluster.rst

@@ -0,0 +1,21 @@
+.. _adapters.redis_cluster:
+
+========================================
+Redis Cluster Adapter (`redisCluster`)
+========================================
+
+Factory:
+
+`Cache::redisCluster(string $namespace = 'default', array $seeds = ['127.0.0.1:6379'], float $timeout = 1.0, float $readTimeout = 1.0, bool $persistent = false, ?object $client = null)`
+
+Requirements:
+
+* RedisCluster support via `ext-redis`, or
+* injected client exposing expected methods (`get`, `set`, `setex`, `del`, `exists`, `sAdd`, `sRem`, `sCard`, `sMembers`)
+
+Highlights:
+
+* cluster-aware storage
+* tracks namespace key membership through an index set (`<ns>:__keys`) for clear/count operations
+
+Useful when using Redis Cluster topology.