README

A trait for building type-safe caching wrappers.

Requirements

PHP 8.0+
PSR-6 cache implementation

Installation

composer require coroq/with-cache

Quick Start

Create a caching decorator class that wraps your original class. When a method is called, the result is cached. Subsequent calls with the same arguments return the cached result without calling the origin.

<?php

use Coroq\Cache\WithCache;
use Psr\Cache\CacheItemPoolInterface;

// Your existing interface
interface UserRepository {
    public function findById(int $id): ?User;
}

// Your existing implementation (no caching logic here)
class DatabaseUserRepository implements UserRepository {
    public function findById(int $id): ?User {
        // fetch from database
    }
}

// Caching decorator - implements same interface
class CachedUserRepository implements UserRepository {
    use WithCache;  // this library

    public function __construct(
        UserRepository $origin,           // the real repository
        CacheItemPoolInterface $cache,    // PSR-6 cache pool
    ) {
        $this->setCacheOrigin($origin);
        $this->setCachePool($cache);
    }

    public function findById(int $id): ?User {
        // delegates to origin, caches the result
        return $this->withCache();
    }
}

// Usage
$repository = new CachedUserRepository(
    new DatabaseUserRepository($pdo),
    $cachePool,
);
$user = $repository->findById(1);  // calls database
$user = $repository->findById(1);  // returns cached result
$user = $repository->findById(2);  // different argument, calls database

Benefits

Separation of concerns - The wrapper class adds caching around the original object. The original class can focus on pure business logic without any knowledge of caching.
Respects types - The wrapper class implements the same interface as the original, with real methods and real type hints. IDE autocompletion works. Static analyzers like PHPStan understand your code. You can swap between cached and non-cached versions in your DI container.

Usage

Basic Caching

Each method that should be cached calls withCache():

class CachedProductService implements ProductService {
    use WithCache;

    public function __construct(ProductService $origin, CacheItemPoolInterface $cache) {
        $this->setCacheOrigin($origin);
        $this->setCachePool($cache);
    }

    public function getById(int $id): ?Product {
        return $this->withCache();
    }

    public function getPopular(int $limit): array {
        return $this->withCache();
    }
}

Bypassing Cache

Use withoutCache() to skip caching for specific calls:

public function getById(int $id): ?Product {
    return $this->withoutCache();  // always calls origin
}

Handling Cache Errors

Cache exceptions can be caught per-method:

use Psr\Cache\CacheException;

public function getById(int $id): ?Product {
    try {
        return $this->withCache();
    } catch (CacheException) {
        // fall back to origin on cache failure
        return $this->withoutCache();
    }
}

Custom TTL

By default, cached items have no expiration (live until the cache evicts them). Override getCacheTtl() to control expiration:

class CachedProductService implements ProductService {
    use WithCache;

    // ...

    protected function getCacheTtl(string $methodName, array $arguments, mixed $result): ?int {
        // return seconds, or null for no expiration
        return match($methodName) {
            'getPopular' => 300,      // 5 minutes
            'getById' => 3600,        // 1 hour
            default => null,
        };
    }
}

TTL can depend on the result:

protected function getCacheTtl(string $methodName, array $arguments, mixed $result): ?int {
    if ($result === null) {
        return 60;  // cache "not found" briefly
    }
    return 3600;
}

Custom Cache Key

Override makeCacheKey() to customize key generation:

protected function makeCacheKey(string $methodName, array $arguments): string {
    // default: sha1(class + method + serialized arguments)
    return "product.$methodName." . sha1(serialize($arguments));
}

Note: Arguments must be serializable. Closures, resources, and some anonymous classes cannot be used as arguments for cached methods.

Static Methods

Static methods cannot be cached with this trait. If the original class has static methods, implement them by calling the original directly:

public static function create(): self {
    return DatabaseUserRepository::create();
}

Cache Invalidation

The trait provides two protected methods for cache invalidation:

clearCache() - clears all cached items in the pool
deleteCacheItem(string $methodName, mixed ...$arguments) - deletes a specific cached result

Use these inside your cached class to invalidate stale entries:

class CachedUserRepository implements UserRepository {
    use WithCache;

    // ...

    public function findById(int $id): ?User {
        return $this->withCache();
    }

    public function update(int $id, array $data): void {
        $this->withoutCache();
        $this->deleteCacheItem('findById', $id);
    }

    public function importFromCsv(string $path): void {
        $this->withoutCache();
        $this->clearCache();  // bulk operation, clear everything
    }
}

Note: clearCache() calls clear() on the underlying cache pool. If you need isolated clearing per service, configure separate cache pools.

License

MIT

coroq / with-cache

Maintainers

Details