Scrapbook
PHP cache library, with adapters for e.g. Memcached, Redis, Couchbase, APC(u), SQL and additional capabilities (e.g. transactions, stampede protection) built on top.
Install / Use
/learn @matthiasmullie/ScrapbookREADME
Documentation: https://www.scrapbook.cash - API reference: https://docs.scrapbook.cash
Table of contents
Installation & usage
Simply add a dependency on matthiasmullie/scrapbook to your composer.json file
if you use Composer to manage the dependencies of
your project:
composer require matthiasmullie/scrapbook
The exact bootstrapping will depend on which adapter, features and interface you will want to use, all of which are detailed below.
This library is built in layers that are all KeyValueStore implementations that you can wrap inside one another if you want to add more features.
Here's a simple example: a Memcached-backed psr/cache with stampede protection.
// create \Memcached object pointing to your Memcached server
$client = new \Memcached();
$client->addServer('localhost', 11211);
// create Scrapbook KeyValueStore object
$cache = new \MatthiasMullie\Scrapbook\Adapters\Memcached($client);
// create stampede protector layer over our real cache
$cache = new \MatthiasMullie\Scrapbook\Scale\StampedeProtector($cache);
// create Pool (psr/cache) object from cache engine
$pool = new \MatthiasMullie\Scrapbook\Psr6\Pool($cache);
// get item from Pool
$item = $pool->getItem('key');
// get item value
$value = $item->get();
// ... or change the value & store it to cache
$item->set('updated-value');
$pool->save($item);
Just take a look at this "build your cache" section to generate the exact configuration you'd like to use (adapter, interface, features) and some example code.
Adapters
Memcached
Memcached is an in-memory key-value store for small chunks of arbitrary data (strings, objects) from results of database calls, API calls, or page rendering.
The PECL Memcached extension is used
to interface with the Memcached server. Just provide a valid \Memcached object
to the Memcached adapter:
// create \Memcached object pointing to your Memcached server
$client = new \Memcached();
$client->addServer('localhost', 11211);
// create Scrapbook KeyValueStore object
$cache = new \MatthiasMullie\Scrapbook\Adapters\Memcached($client);
Redis
Redis is often referred to as a data structure server since keys can contain strings, hashes, lists, sets, sorted sets, bitmaps and hyperloglogs.
The PECL Redis extension is used
to interface with the Redis server. Just provide a valid \Redis object
to the Redis adapter:
// create \Redis object pointing to your Redis server
$client = new \Redis();
$client->connect('127.0.0.1');
// create Scrapbook KeyValueStore object
$cache = new \MatthiasMullie\Scrapbook\Adapters\Redis($client);
Couchbase
Engineered to meet the elastic scalability, consistent high performance, always-on availability, and data mobility requirements of mission critical applications.
The PECL Couchbase extension and
couchbase/couchbase package
are used to interface with the Couchbase server. Just provide valid
\Couchbase\Collection, \Couchbase\Management\BucketManager and
\Couchbase\Bucket objects to the Couchbase adapter:
// create \Couchbase\Bucket object pointing to your Couchbase server
$options = new \Couchbase\ClusterOptions();
$options->credentials('username', 'password');
$cluster = new \Couchbase\Cluster('couchbase://localhost', $options);
$bucket = $cluster->bucket('default');
$collection = $bucket->defaultCollection();
$bucketManager = $cluster->buckets();
// create Scrapbook KeyValueStore object
$cache = new \MatthiasMullie\Scrapbook\Adapters\Couchbase($collection, $bucketManager, $bucket);
APCu
APC is a free and open opcode cache for PHP. Its goal is to provide a free, open, and robust framework for caching and optimizing PHP intermediate code.
With APC, there is no "cache server", the data is just cached on the executing machine and available to all PHP processes on that machine. The PECL APCu extension can be used.
// create Scrapbook KeyValueStore object
$cache = new \MatthiasMullie\Scrapbook\Adapters\Apc();
MySQL
MySQL is the world's most popular open source database. MySQL can cost-effectively help you deliver high performance, scalable database applications.
While a database is not a genuine cache, it can also serve as key-value store. Just don't expect the same kind of performance you'd expect from a dedicated cache server.
But there could be a good reason to use a database-based cache: it's convenient if you already use a database, and it may have other benefits (like persistent storage, replication.)
// create \PDO object pointing to your MySQL server
$client = new PDO('mysql:dbname=cache;host=127.0.0.1', 'root', '');
// create Scrapbook KeyValueStore object
$cache = new \MatthiasMullie\Scrapbook\Adapters\MySQL($client);
PostgreSQL
PostgreSQL has a proven architecture that has earned it a strong reputation for reliability, data integrity, and correctness.
While a database is not a genuine cache, it can also serve as key-value store. Just don't expect the same kind of performance you'd expect from a dedicated cache server.
But there could be a good reason to use a database-based cache: it's convenient if you already use a database, and it may have other benefits (like persistent storage, replication.)
// create \PDO object pointing to your PostgreSQL server
$client = new PDO('pgsql:user=postgres dbname=cache password=');
// create Scrapbook KeyValueStore object
$cache = new \MatthiasMullie\Scrapbook\Adapters\PostgreSQL($client);
SQLite
SQLite is a software library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine.
While a database is not a genuine cache, it can also serve as key-value store. Just don't expect the same kind of performance you'd expect from a dedicated cache server.
// create \PDO object pointing to your SQLite server
$client = new PDO('sqlite:cache.db');
// create Scrapbook KeyValueStore object
$cache = new \MatthiasMullie\Scrapbook\Adapters\SQLite($client);
Filesystem
While it's not the fastest kind of cache in terms of I/O access times, opening a file usually still beats redoing expensive computations.
The filesystem-based adapter uses league\flysystem to abstract away the file
operations, and will work with all kinds of storage that league\filesystem
provides.
// create Flysystem object
$adapter = new \League\Flysystem\Local\LocalFilesystemAdapter('/path/to/cache', null, LOCK_EX);
$filesystem = new \League\Flysystem\Filesystem($adapter);
// create Scrapbook KeyValueStore object
$cache = new \MatthiasMullie\Scrapbook\Adapters\Flysystem($filesystem);
Memory
PHP can keep data in memory, too! PHP arrays as storage are particularly useful to run tests against, since you don't have to install any other service.
Stuffing values in memory is mostly useless: they'll drop out at the end of the request. Unless you're using these cached values more than once in the same request, cache will always be empty and there's little reason to use this cache.
However, it is extremely useful when unittesting: you can run your entire test suite on this memory-based store, instead of setting up cache services and making sure they're in a pristine state...
// create Scrapbook KeyValueStore object
$cache = new \MatthiasMullie\Scrapbook\Adapters\MemoryStore();
Features
In addition to the default cache functionality (like get & set), Scrapbook
comes with a few neat little features. These are all implemented in their own
little object that implements KeyValueStore, and wraps around a KeyValueStore.
In other words, any feature can just be wrapped inside another one or on top
of any adapter.
Local buffer
BufferedStore helps reduce requests to your real cache. If you need to request the same value more than once (from various places in your code), it can be a pain to keep that value around. Requesting it again from cache would be easier, but then you get some latency from the co
