Search by

gadwinn / psr-simple-cache

Gadwinn

PSR-16 simple cache with swappable storage drivers (in-memory, file system).

Package info

github.com/Gadwinn/psr-simple-cache

pkg:composer/gadwinn/psr-simple-cache

Statistics

Installs: 1

Dependents: 0

Suggesters: 2

Stars: 0

Open Issues: 0

v0.1.0 2026-11-17 15:01 UTC

This package is auto-updated.

Last update: 2026-11-18 11:22:37 UTC


README

A PSR-16 compliant caching library for PHP 8.3+, built around a swappable storage driver architecture.

Tech Stack

  • PHP 8.3+
  • PSR-16 (psr/simple-cache: ^3.0) — CacheInterface contract
  • Drivers — ArrayStorage (in-memory), FileStorage (file-system)

Installation

composer require gadwinn/psr-simple-cache

Usage

Instantiation

use G\SimpleCache\Cache;
use G\SimpleCache\Storage\ArrayStorage;
use G\SimpleCache\Storage\FileStorage;

// In-memory (default) — no persistence across requests
$cache = new Cache();

// In-memory with a default TTL of 300 seconds
$cache = new Cache(new ArrayStorage(), defaultTtl: 300);

// File-system — persists across requests
$cache = new Cache(new FileStorage('/var/cache/myapp'));

// File-system with a default TTL
$cache = new Cache(new FileStorage('/var/cache/myapp'), defaultTtl: 3600);

The constructor signature:

public function __construct(
    StorageInterface $storage = new ArrayStorage(),
    ?int $defaultTtl = null
)

defaultTtl applies whenever set() or setMultiple() is called without an explicit TTL. null means cache forever.

Basic read / write

$cache->set('user.42', $userObject);

$user = $cache->get('user.42');           // returns the value
$user = $cache->get('missing', $default); // returns $default on miss

$cache->has('user.42'); // bool

$cache->delete('user.42');
$cache->clear();

TTL

Accepts an int (seconds) or a DateInterval:

// Expires in 10 minutes
$cache->set('token', $jwt, 600);

// Expires via DateInterval
$cache->set('token', $jwt, new DateInterval('PT10M'));

// A zero or negative TTL deletes the item immediately (PSR-16 §1.2)
$cache->set('stale_key', $value, -1);

Batch operations

// Write multiple entries (same TTL for all)
$cache->setMultiple([
    'config.db'    => $dbConfig,
    'config.cache' => $cacheConfig,
], ttl: 3600);

// Read multiple entries with a shared default
$results = $cache->getMultiple(['config.db', 'config.cache'], default: []);

// Delete multiple entries
$cache->deleteMultiple(['config.db', 'config.cache']);

Key rules

A key is any non-empty string that contains none of the characters reserved by PSR-16: {}()/\@:. There is no length limit. In getMultiple(), setMultiple() and deleteMultiple(), integer keys are accepted and cast to strings (PHP turns numeric string array keys into integers), and every key is validated before anything is written or deleted.
Any invalid key throws G\SimpleCache\InvalidArgumentException (implements Psr\SimpleCache\InvalidArgumentException).

Custom storage driver

Implement G\SimpleCache\Storage\StorageInterface:

use G\SimpleCache\Storage\StorageInterface;

class RedisStorage implements StorageInterface
{
    public function __construct(private readonly \Redis $redis) {}

    public function read(string $key): ?array
    {
        $raw = $this->redis->get($key);
        if ($raw === false) {
            return null;
        }
        $data = unserialize($raw, ['allowed_classes' => true]);
        return is_array($data) ? $data : null;
    }

    public function write(string $key, mixed $value, ?int $expiresAt): void
    {
        $ttl = $expiresAt !== null ? max(1, $expiresAt - time()) : 0;
        $this->redis->set($key, serialize(compact('value', 'expiresAt')), $ttl);
    }

    public function remove(string $key): void
    {
        $this->redis->del($key);
    }

    public function flush(): void
    {
        $this->redis->flushDB();
    }
}

$cache = new Cache(new RedisStorage($redis));

A driver reports a failed write, removal or flush by throwing any exception: Cache turns it into the false result required by PSR-16 (set(), delete(), clear(), setMultiple(), deleteMultiple()). Removing a missing entry is not a failure.

FileStorage writes each entry to a temporary file and renames it, so a concurrent reader never sees a partial file; an unreadable or corrupted file is a cache miss.

The interface contract:

interface StorageInterface
{
    /** @return array{value: mixed, expiresAt: int|null}|null */
    public function read(string $key): ?array;

    /** @param int|null $expiresAt Absolute Unix timestamp, or null for no expiry. */
    public function write(string $key, mixed $value, ?int $expiresAt): void;

    public function remove(string $key): void;
    public function flush(): void;
}

License

MIT, see LICENSE.