Simple PHP caching library -- by, Chris Kankiewicz (@PHLAK)

Stash is a simple 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.

Like this project? Keep me caffeinated by making a donation.

• PHP >= 5.4

composer require phlak/stash

First, import Stash:

use PHLAK\Stash;

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

Stash\Cache::file($config);
Stash\Cache::memcached($config);
Stash\Cache::redis($config);
Stash\Cache::apcu($config);
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.

Alternatively you may use the Stash\Cache::make() factory method to instantiate your driver.

$stash = Stash\Cache::make($driver, $config);

The make() method takes two parameters. The first ($driver) should be one of the following lowercase strings representing your desired caching driver.

• apcu
• ephemeral
• file
• memcached
• redis

The second ($config) is the same driver-specific configuration closure as when using a named constructor. Refer to the specific documentation about each driver below for more info.

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 () {
    $this->setCacheDir('path/to/cache');
});

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 server via the addServer() or addServers() methods.

Reference the PHP Memcached documentation for additional configuration options.

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

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 server via the connect() or pconnect() methods.

Reference the phpredis documentation for additional configuration options.

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

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 () {
    $this->setPrefix('some_prefix');
});

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();

Add an item to the cache for a specified duration.

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

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

Add an item to the cache permanently.

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

Retrieve an item from the cache.

$stash->get('foo');

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

Check if an item exists in the cache.

$stash->has('foo');

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.

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

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.

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

Increment an integer already stored in the cache.

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

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

Decrement an integer already stored in the cache.

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

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

Extend the expiration time for an item in the cache.

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

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

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

Remove an item from the cache.

$stash->forget('foo');

Delete all items from the cache.

$stash->flush();

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

Please report bugs to the GitHub Issue Tracker.

This project is licensed under the MIT License.