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

apix / cache

Maintainers

Details