phlak / stash Goto Github PK

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

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.

• PHP >= 7.2

composer require phlak/stash

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.

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 (): void {
    $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 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');
});

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');
});

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');
});

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.

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

Please report bugs to the GitHub Issue Tracker.

This project is licensed under the MIT License.