README

puff/cache provides Memory, Array, Fiber-local, Files, and APCu cache drivers. The Cache manager can be used as a standalone object and also integrates with Puff through Composer discovery, dependency injection, a facade, and the cache() helper.

composer require puff/cache

Basic usage

<?php

use Puff\Cache\Cache;

$cache = new Cache('memory', [
    'memory' => [
        'prefix' => 'app:',
        'size' => 1024,
    ],
]);

$cache->set('name', 'Puff', 60);
echo $cache->get('name');

$cache->sets(['one' => 1, 'two' => 2], 60);
$values = $cache->gets(['one', 'two']);

$report = $cache->remember('report', static function (): array {
    return ['generated' => true];
}, 300);

$cache->delete('name');
$cache->clear();

TTL values are expressed in seconds. A TTL less than or equal to 0 means that the item does not expire automatically.

All built-in drivers inherit prefix management and the default puff prefix from AbstractDriver:

$driver = $cache->driver();
echo $driver->prefix();
$driver->prefix('tenant:');

Changing the prefix switches the active cache namespace. Files Driver rejects empty prefixes and path separators; Fiber Driver propagates changes to stores that have already been created.

Drivers

Memory

The Memory driver stores values in the current PHP process and enforces a maximum number of items. When the limit is reached, it first removes expired entries and then evicts the oldest entry.

$cache = new Cache('memory', [
    'memory' => [
        'prefix' => 'app:',
        'size' => 1024,
    ],
]);

Use it for long-running workers that need a bounded local cache. Values are not shared between worker processes.

Array

The Array driver is an unbounded in-process cache. It is useful for tests and short-lived tasks where capacity management is unnecessary.

$cache = new Cache('array', [
    'array' => ['prefix' => 'test:'],
]);

Values are not shared between worker processes.

Fiber-local

The Fiber driver creates an isolated Array store for the main execution context and for every Fiber.

$cache = new Cache('fiber', [
    'fiber' => ['prefix' => 'request:'],
]);

The same key can hold different values in different Fibers. Fiber stores are held through weak references and can be released when their Fiber objects are released. clear() only clears the current Fiber or main-context store.

Use this driver for request-scoped or task-scoped temporary data. It is not a shared application cache.

Files

The Files driver persists JSON-compatible values on the local filesystem.

$cache = new Cache('files', [
    'files' => [
        'dir' => __DIR__ . '/runtime/cache',
        'prefix' => 'app.',
        'append' => '.bin',
    ],
]);

Writes use a temporary file followed by an atomic rename. Expiration timestamps are stored inside the cache payload, and corrupt or expired entries are removed when read. Values must be JSON-encodable.

The current file format is not compatible with the legacy mtime-based format. Legacy entries are treated as invalid and removed automatically.

APCu

The APCu driver shares values between PHP workers on the same host when APCu is configured for that runtime.

$cache = new Cache('apc', [
    'apc' => ['prefix' => 'app:'],
]);

The APCu extension must be installed and enabled. clear() removes only keys that belong to the configured prefix.

Custom drivers

A custom driver must implement Puff\Cache\Contract:

use Puff\Cache\Contract;

$cache->extend('custom', static function (array $config): Contract {
    return new CustomDriver($config);
});

$cache->setDefaultDriver('custom');

Puff\Cache\Driver\AbstractDriver provides default implementations of gets(), sets(), and remember(). Extending it is optional; third-party drivers may implement Contract directly.

Puff configuration

'cache' => [
    'default' => 'memory',
    'memory' => [
        'size' => 1024,
    ],
    'array' => [],
    'fiber' => [],
    'files' => [
        'dir' => \dirname(__DIR__) . '/runtime/cache',
        'append' => '.bin',
    ],
    'apc' => [],
],

Composer discovers Puff\Cache\ServiceProvider automatically. The cache can then be resolved from the container, facade, or helper:

$cache = app('cache');
$value = cache('name', 'default');

The cache() helper uses has() to distinguish a missing key from a cached null value.

Validation

composer test
composer analyse

puff / cache

Maintainers

Package info

Statistics

Security