phlak/stash

Simple PHP caching library

8.0.0 2025-07-25 18:06 UTC

Requires

• php: >= 8.1
• nesbot/carbon: ^3.0

Requires (Dev)

• phlak/coding-standards: ^4.0
• phpstan/phpstan: ^2.0
• symfony/var-dumper: ^6.0 || ^7.0
• yoast/phpunit-polyfills: ^4.0

Suggests

• ext-apcu: Required to use the APCu cache driver.
• ext-memcached: Required to use the Memcached driver.
• ext-redis: Required to use the Redis cache driver.

MIT

• Chris Kankiewicz

README

Lightweight PHP caching library • Created by Chris Kankiewicz (@PHLAK.dev)

Introduction

Stash is a lightweight PHP caching library supporting multiple, interchangeable caching back-ends and an expressive (Laravel inspired) API.

Supported caching back-ends:

• File - File-based caching. Stores cache items as files in a directory on disk.
• Memcached - High-performance, distributed memory object caching system
• Redis - In-memory data structure store.
• APCu - PHP's native APC User Cache.
• Ephemeral - A transient, in-memory array that only exists for the lifetime of the script.

Requirements

• PHP >= 8.1

Install with Composer

composer require phlak/stash

Initializing the Client

First, import Stash:

use PHLAK\Stash;

Then instantiate Stash for your back-end of choice with the named constructor:

$stash = Stash\Cache::file($config);
$stash = Stash\Cache::memcached($config);
$stash = Stash\Cache::redis($config);
$stash = Stash\Cache::apcu($config);
$stash = Stash\Cache::ephemeral();

The $config parameter accepts a driver-specific closure for setting configuration options for your chosen driver. Refer to the specific documentation about each driver below for more info. Not all drivers require a configuration function.

File Cache

The file cache configuration closure must call $this->setCacheDir($path) where $path is a path to a valid directory in which your cache files will be stored.

$stash = Stash\Cache::file(function (): void {
    $this->setCacheDir('path/to/cache');
});

Memcached

The Memcached configuration closure receives an instance of the Memcached object as it's only parameter, you can use this parameter to connect and configure Memcached. At a minimum you must connect to one or more Memcached servers via the addServer() or addServers() methods.

Reference the PHP Memcached documentation for additional configuration options.

$stash = Stash\Cache::memcached(function (Memcached $memcached): void {
    $memcached->addServer('localhost', 11211);
    // $memcached->setOption(Memcached::OPT_PREFIX_KEY, 'some_prefix');
});

Redis

The Redis configuration closure receives an instance of the Redis object as it's only parameter, you can use this parameter to connect to and configure Redis. At a minimum you must connect to one or more Redis servers via the connect() or pconnect() methods.

Reference the phpredis documentation for additional configuration options.

$stash = Stash\Cache::redis(function (Redis $redis): void {
    $redis->pconnect('localhost', 6379);
    // $redis->setOption(Redis::OPT_PREFIX, 'some_prefix');
});

APCu

The APCu driver caches items in PHPs APC user cache.

$stash = Stash\Cache::apcu();

The APCu driver does not require a configuration closure. However, if you wish to set a cache prefix you may pass a configuration closure that calls $this->setPrefix($prefix) where $prefix is a string of your desired prefix.

$stash = Stash\Cache::apcu(function (): void {
    $this->setPrefix('some_prefix');
});

Ephemeral

The Ephemeral driver caches items in a PHP array that exists in memory only for the lifetime of the script. The Ephemeral driver does not take a configuration closure.

$stash = Stash\Cache::ephemeral();

Usage

Cacheable::put( string $key , mixed $data [, $ttl = 0 ] ) : bool

Add an item to the cache for a specified duration.

Examples

// Cache a value for 5 minutes
$stash->put('foo', 'some value', 300);

// Cache a value indefinitely
$stash->put('bar', false);

Cacheable::forever( string $key , mixed $data) : bool

Add an item to the cache permanently.

Examples

$stash->forever('foo', 'some value');

Cacheable::get( string $key [, $default = false ] ) : mixed

Retrieve an item from the cache.

Examples

$stash->get('foo');

// Return 'default' if 'bar' doesn't exist
$stash->get('bar', 'default');

Cacheable::has( string $key ) : bool

Check if an item exists in the cache.

Examples

$stash->has('foo');

Cacheable::remember( string $key , int $ttl , Closure $closure ) : mixed

Retrieve item from cache or, when item does not exist, execute a closure. The result of the closure is then stored in the cache for the specified duration and returned for immediate use.

Examples

$stash->remember('foo', 60, function() {
    return new FooClass();
});

Cacheable::rememberForever( string $key , Closure $closure ) : mixed

Retrieve item from cache or, when item does not exist, execute a closure. The result of the closure is then stored in the cache permanently.

Examples

$stash->rememberForever('pokemon', function() {
    return new Pokemon($name, $description);
});

Cacheable::increment( string $key [, int $value = 1 ] ) : mixed

Increment an integer already stored in the cache.

Examples

// Increment by 1
$stash->increment('foo');

// Increment by 10
$stash->increment('bar', 10);

Cacheable::decrement( string $key [, int $value = 1 ] ) : mixed

Decrement an integer already stored in the cache.

Examples

 // Decrements by 1
$stash->decrement('foo');

 // Decrements by 10
$stash->decrement('bar', 10);

Cacheable::touch( string|array $key [, int $ttl = 0 ] ) : bool

Extend the expiration time for an item in the cache.

Examples

 // Extend the expiration by 5 minutes
$stash->touch('foo', 300);

 // Extend the expiration indefinitely
$stash->touch('bar');

// Extend the expiration of multiple items by 5 minutes
$stash->touch(['foo', 'bar', 'baz'], 300);

Cacheable::forget( string $key ) : bool

Remove an item from the cache.

Examples

$stash->forget('foo');

Cacheable::flush() : bool

Delete all items from the cache.

Examples

$stash->flush();

TTL Helper

For convenience, Stash provides a TTL helper class to convert units of time to seconds. This is useful for setting the $ttl parameter in various methods.

Examples

use PHLAK\Stash\TTL;

// Cache a value for 5 minutes
$stash->put('foo', 'some value', TTL::minutes(5));

// Remember an item for one day
$stash->remember('bar', TTL::days(1), fn (): string => 'Some value');

// Update the expiration time of an item to 3 hour
$stash->touch('baz', TTL::hours(3));

Changelog

A list of changes can be found on the GitHub Releases page.

Troubleshooting

For general help and support join our GitHub Discussions or reach out on Bluesky.

Please report bugs to the GitHub Issue Tracker.

Copyright

This project is licensed under the MIT License.