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