Apix Cache, cache-tagging for PHP

Apix Cache is a generic and thin cache wrapper with a PSR-6 interface to various caching backends and emphasising cache tagging and indexing.

Cache-tagging allows to find/update all data items with one or more given tags. Providing, for instance, a batch delete of all obsolete entries matching a speficic tag such as a version string.

• Fully unit-tested and compliant with PSR-1, PSR-2, PSR-4 and PSR-6 (Cache).
• Continuously integrated
  • against PHP5.3, 5.4, 5.5, 5.6, 7.0, 7.1, 7.2, 7.3and HHVM,
  • and against APC, APCu, Redis, MongoDB, Sqlite, MySQL, PgSQL and Memcached, ...
  • supports a range of serializers: igBinary, msgpack, json, php, ...
• Extendable, additional extensions are available:
  • apix/simple-cache provides a SimpleCache (PSR-16) interface.
  • More contributions will be linked here.
• Available as a Composerand as a PEAR package.

⇄ Pull requests and ★ Stars are always welcome. For bugs and feature request, please create an issue.

---

Cache backends

Currently, the following cache store are supplied:

• APCu and APCwith tagging support,
• Redis using the PhpRedis extension with tagging support,
• MongoDB using either the new mongodb or the legacy mongo extension with tagging support,
• Memcached using the Memcached extension with indexing, tagging and namespacing support,
• and relational databases using PDOwith tagging support:
  • Dedicated drivers for SQLite, PostgreSQL and MySQL (also works with Amazon Aurora, MariaDB and Percona),
  • A generic Sql1999 driver for 4D, Cubrid, SQL Server, Sybase, Firebird, ODBC, Interbase, IBM DB2, IDS, Oracle...
• Directory and Files based with tagging support,
• Runtime, in-memory array storage.

Factory usage (PSR-Cache wrapper)

useApix\Cache;
$backend = new \Redis();
#$backend = new \PDO('sqlite:...'); // Any supported client object e.g. Memcached, MongoClient, ...#$backend = new Cache\Files($options); // or one that implements Apix\Cache\Adapter#$backend = 'apcu'; // or an adapter name (string) e.g. "APC", "Runtime"#$backend = new MyArrayObject(); // or even a plain array() or \ArrayObject.$cache = Cache\Factory::getPool($backend); // without tagging support#$cache = Cache\Factory::getTaggablePool($backend); // with tagging$item = $cache->getItem('wibble_id');
if ( !$cache->isHit() ) {
$data = compute_expensive_stuff();
$item->set($data);
$cache->save($item);
}
return$item->get();

Basic usage (Apix native)

useApix\Cache;
$cache = newCache\Apcu;
// try to retrieve 'wibble_id' from the cacheif ( !$data = $cache->load('wibble_id') ) {
// otherwise, get some data from the origin// example of arbitrary mixed data$data = array('foo' => 'bar');
// and save it to the cache$cache->save($data, 'wibble_id');
}

You can also use the folowing in your use cases:

// save $data to the cache as 'wobble_id',// tagging it along the way as 'baz' and 'flob',// and set the ttl to 300 seconds (5 minutes)$cache->save($data, 'wobble_id', array('baz', 'flob'), 300);
// retrieve all the cache ids under the tag 'baz'$ids = $cache->loadTag('baz');
// clear out all items with a 'baz' tag$cache->clean('baz');
// remove the named item$cache->delete('wibble_id');
// flush out the cache (of all -your- stored items)$cache->flush();

Advanced usage

Options shared by all the backends

useApix\Cache;
// default options$options = array(
'prefix_key' => 'apix-cache-key:', // prefix cache keys'prefix_tag' => 'apix-cache-tag:', // prefix cache tags'tag_enable' => true// wether to enable tags support
);
// start APCu as a local cache$local_cache = newCache\Apcu($options);

Redis specific

// additional (default) options$options['atomicity'] = false; // false is faster, true is guaranteed$options['serializer'] = 'php'; // null, php, igbinary, json and msgpack$redis_client = new \Redis; // instantiate phpredis*$distributed_cache = newCache\Redis($redis_client, $options);

* see PhpRedis for instantiation usage.

Memcached specific

// additional (default) options, specific to Memcached$options['prefix_key'] = 'key_'; // prefix cache keys$options['prefix_tag'] = 'tag_'; // prefix cache tags$options['prefix_idx'] = 'idx_'; // prefix cache indexes$options['prefix_nsp'] = 'nsp_'; // prefix cache namespaces$options['serializer'] = 'auto'; // auto, igbinary, msgpack, php, json and json_array.$memcached = new \Memcached; // a Memcached*** instance$shared_cache = newCache\Memcached($memcached, $options);

The serialzer auto (default) is igBinary if available, then msgpack if available, then php otherwise.

*** see Memcached for instantiation details.

MongoDB specific

// additional (default) options$options['object_serializer'] = 'php'; // null, json, php, igBinary$options['db_name'] = 'apix'; // name of the mongo db$options['collection_name'] = 'cache'; // name of the mongo collection$mongo = new \MongoDB\Client; // MongoDB native driver#$mongo = new \MongoClient; // or MongoDB legacy driver$cache = newCache\Mongo($mongo, $options);

PDO specific

// additional (default) options, specific to the PDO backends$options['db_table'] = 'cache'; // table to hold the cache$options['serializer'] = 'php'; // null, php, igbinary, json and msgpack$options['preflight'] = true; // wether to preflight the DB$options['timestamp'] = 'Y-m-d H:i:s'; // the timestamp DB format// with SQLITE$dbh = new \PDO('sqlite:/tmp/apix_tests.sqlite3');
$relational_cache = newCache\Pdo\Sqlite($dbh, $options);
// with MYSQL, MariaDB and Percona$dbh = new \PDO('mysql:host=xxx;port=xxx;dbname=xxx', 'user', 'pass');
$mysql_cache = newCache\Pdo\Mysql($dbh, $options);
// with PGSQL$dbh = new \PDO('pgsql:dbname=xxx;host=xxx', 'xxx', 'xxx');
$postgres_cache = newCache\Pdo\Pgsql($dbh, $options);
// with a SQL:1999 compliant DB, e.g. Oracle$dbh = new \PDO('oci:dbname=xxx', 'xxx', 'xxx');
$sql1999_cache = newCache\Pdo\Sql1999($dbh, $options);

The preflight option will create on-the-fly the required tables if these are mssing. Once these tables exist, set preflight to false in order to avoid the extraneous checks.

Filesystem specific

// additional (default) options$options['directory'] = sys_get_temp_dir() . '/apix-cache'; // Directory where the cache is created$options['locking'] = true; // File locking (recommended)$files_cache = newCache\Files($options);
// or$directory_cache = newCache\Directory($options); 

• Files: the cache metadata (expiration time and tags) are stored in the cache file directly.
• Directory: the metadata are stored separately from the cached data.

Installation

This project adheres to Semantic Versioning and can be installed using composer:

$ composer require apix/cache:^1.3

All notable changes to this project are documented in its CHANGELOG.

License

This work is licensed under the New BSD license -- see the LICENSE for the full details.
Copyright (c) 2010-2016 Franck Cassedanne