https://github.com/phlak/stash
Simple PHP caching library
https://github.com/phlak/stash
apcu caching file-cache memcached php redis
Last synced: 8 months ago
JSON representation
Simple PHP caching library
- Host: GitHub
- URL: https://github.com/phlak/stash
- Owner: PHLAK
- License: mit
- Created: 2016-04-06T01:17:16.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-02-01T11:00:44.000Z (over 3 years ago)
- Last Synced: 2025-03-26T12:46:41.087Z (over 1 year ago)
- Topics: apcu, caching, file-cache, memcached, php, redis
- Language: PHP
- Homepage: https://packagist.org/packages/phlak/stash
- Size: 475 KB
- Stars: 7
- Watchers: 2
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
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](https://php.net) >= 8.1
Install with Composer
---------------------
```bash
composer require phlak/stash
```
Initializing the Client
-----------------------
First, import Stash:
```php
use PHLAK\Stash;
```
Then instantiate Stash for your back-end of choice with the named constructor:
```php
$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](https://secure.php.net/manual/en/class.closure.php)
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.
```php
$stash = Stash\Cache::file(function (): void {
$this->setCacheDir('path/to/cache');
});
```
#### Memcached
The Memcached configuration closure receives an instance of the
[Memcached object](https://www.php.net/manual/en/class.memcached.php) 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](https://secure.php.net/manual/en/book.memcached.php)
for additional configuration options.
```php
$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](https://github.com/phpredis/phpredis#class-redis) 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](https://github.com/phpredis/phpredis#readme)
for additional configuration options.
```php
$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.
```php
$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.
```php
$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.
```php
$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
```php
// 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
```php
$stash->forever('foo', 'some value');
```
---
### `Cacheable::get( string $key [, $default = false ] ) : mixed`
Retrieve an item from the cache.
##### Examples
```php
$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
```php
$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
```php
$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
```php
$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
```php
// 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
```php
// 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
```php
// 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
```php
$stash->forget('foo');
```
---
### `Cacheable::flush() : bool`
Delete all items from the cache.
##### Examples
```php
$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
```php
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](https://github.com/PHLAK/Stash/releases) page.
Troubleshooting
---------------
For general help and support join our [GitHub Discussions](https://github.com/PHLAK/Stash/discussions) or reach out on [Bluesky](https://bsky.app/profile/phlak.dev).
Please report bugs to the [GitHub Issue Tracker](https://github.com/PHLAK/Stash/issues).
Copyright
---------
This project is licensed under the [MIT License](https://github.com/PHLAK/Stash/blob/master/LICENSE).