README

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 PHP 5.3, 5.4, 5.5, 5.6, 7.0, 7.1, 7.2, 7.3 and 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 Composer and 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 APC with 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 PDO with 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)

 use Apix\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)

 use Apix\Cache; $cache = new Cache\Apcu; // try to retrieve 'wibble_id' from the cache if ( !$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

 use Apix\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 = new Cache\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 = new Cache\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 = new Cache\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 = new Cache\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 = new Cache\Pdo\Sqlite($dbh, $options); // with MYSQL, MariaDB and Percona $dbh = new \PDO('mysql:host=xxx;port=xxx;dbname=xxx', 'user', 'pass'); $mysql_cache = new Cache\Pdo\Mysql($dbh, $options); // with PGSQL $dbh = new \PDO('pgsql:dbname=xxx;host=xxx', 'xxx', 'xxx'); $postgres_cache = new Cache\Pdo\Pgsql($dbh, $options); // with a SQL:1999 compliant DB, e.g. Oracle $dbh = new \PDO('oci:dbname=xxx', 'xxx', 'xxx'); $sql1999_cache = new Cache\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 = new Cache\Files($options); // or $directory_cache = new Cache\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