romeoz/rock-cache

Unified API for key-value storages in memory. As a storage can be used: APC, Redis, Memcache, Couchbase or MongoDB. All storage objects have one interface, so you can switch them without changing the working code.

Cache library

, _(*1)

What storages can be used:, _(*2)

• Memcached
• APCu
• Redis
• Couchbase
• MongoDB
• CacheStub (stub for caching)

All storage objects have one interface, so you can switch them without changing the working code., _(*3)

Features

• One interface for all storages - you can change storage without changing your code
• Tagging cache (approach versioning and grouping)
• Locking - "race condition" ("dog-pile" or "cache miss storm") effects are excluded
• Serializer for value (json or PHP-serializer)
• Automatic unserialization
• Standalone module/component for Rock Framework

Table of Contents

• Installation
• Quick Start
  • Memcached
  • MongoDB
  • Locking key
• Documentation
• Demo
• Requirements
• Storages comparison
• Differences between the approaches a tagging
  • Grouping tags
  • Versioning tags

Installation

From the Command Line:, _(*4)

composer require romeoz/rock-cache

or in your composer.json:, _(*5)

{
    "require": {
        "romeoz/rock-cache": "*"
    }
}

Quick Start

Memcached

$config = [
    'hashKey' => CacheInterface::HASH_MD5, // Default: HASH_MD5
    'serializer' => CacheInterface::SERIALIZE_JSON // Default: SERIALIZE_PHP - php serializator
];
$memcached = new \rock\cache\Memcached($config); // or \rock\cache\versioning\Memcached for approach versioning

$tags = ['tag_1', 'tag_2'];
$value = ['foo', 'bar'];
$expire = 0; // If use expire "0", then time to live infinitely
$memcached->set('key_1', $value, $expire, $tags);

// automatic unserialization
$memcached->get('key_1'); // result: ['foo', 'bar'];

$memcached->flush(); // Invalidate all items in the cache

MongoDB

$connection = new \rock\mongodb\Connection;
$collection = $connection->getCollection('cache')
$collection->createIndex('id', ['unique' => true]);
$collection->createIndex('expire', ['expireAfterSeconds' => 0]); // create TTL index

$config = [
    'storage' => $connection,
    'cacheCollection' => 'cache'
];
$mongoCache = new \rock\cache\MongoCache($config);

...

Locking key

Race conditions can occur in multi-threaded mode. To avoid the effect, you need to install a lock on the key., _(*6)

$memcached = new \rock\cache\Memcached

$value = $memcached->get('key_1');
if ($value !== false) {
    return $value;
}

if ($memcached->lock('key_1')) {

    // the query to DBMS or other...

    $memcached->set('key_1', 'foo');
    $memcached->unlock('key_1');
}

Documentation

get($key)

Returns value by key., _(*7)

getMulti(array $keys)

Returns multiple values by keys., _(*8)

set($key, mixed $value, $expire = 0, array $tags = null)

Sets a value to cache., _(*9)

setMulti($key, mixed $value, $expire = 0, array $tags = null)

Sets a multiple key-values to cache., _(*10)

add($key, mixed $value, $expire = 0, array $tags = null)

Adds a value to cache., _(*11)

Return false, if already exists on the server., _(*12)

exists($key)

Checks existence key., _(*13)

touch($key, $expire = 0)

Changes expire (TTL) for key., _(*14)

touchMulti(array $keys, $expire = 0)

Changes expire (TTL) for multiple keys ., _(*15)

increment($key, $offset = 1, $expire = 0, $create = true)

Increment a value to cache., _(*16)

decrement($key, $offset = 1, $expire = 0, $create = true)

Decrement a value to cache., _(*17)

remove($key)

Removes value from cache., _(*18)

removeMulti(array $keys)

Removes multiple values from cache., _(*19)

getTag($tag)

Returns a keys in accordance with tag., _(*20)

getMultiTags(array $tags)

Returns a keys in accordance with multiple tags., _(*21)

existsTag($tag)

Checks existence tag., _(*22)

removeTag($tag)

Removes a tag., _(*23)

removeMultiTag(array $tags)

Removes a multiple tags., _(*24)

getAllKeys()

Returns all keys., _(*25)

Supported: Memcached, Redis, APC., _(*26)

getAll()

Returns all values., _(*27)

Supported: Memcached, APC., _(*28)

lock($key)

Sets a lock on the key., _(*29)

unlock($key)

Unlocking key., _(*30)

flush()

Removes all values from cache., _(*31)

status()

Returns a status server., _(*32)

Supported: Memcached, Memcache, Redis, APC, Couchbase., _(*33)

getStorage()

Returns a native instance cache-storage., _(*34)

Demo

• Install Docker or askubuntu
• docker run --name demo -d -p 8080:80 romeoz/docker-rock-cache
• Open demo http://localhost:8080/

Requirements

You can use each storage separately, requirements are individually for storages., _(*35)

• PHP 5.4+ and 7.0+
• Redis 2.8/3.0/3.2/4.0. Should be installed apt-get install redis-server or docker run --name redis -d -p 6379:6379 romeoz/docker-redis:4.0 (recommended). Also should be installed PHP extension apt-get install php-redis
• Memcached. Should be installed apt-get install memcached or docker run --name memcached -d -p 11211:11211 romeoz/docker-memcached (recommended). Also should be installed php-extension Memcache apt-get install php-memcache or Memcached apt-get install php-memcached. >php-extension Memcached require dependencies
• APCu. Should be installed apt-get install php-apcu. >For PHP 5.6 and lower allowed pecl-extensions APCu 4.0 and lower. Example installation.
• Couchbase DB 4.x.x. PHP 5.6 or higher, php-extension couchbase 2.3.x-2.4.x. Step-by-step installation or docker run --name couchbase -d couchbase/server:community-4.1.1 (Example installation).
• MongoDB 2.6-3.0. For using MongoDB as storage required Rock MongoDB: composer require romeoz/rock-mongodb

All unbolded dependencies is optional, _(*36)

There is a ready docker-container: docker run --name phpfpm_full -d romeoz/docker-phpfpm:5.6-full. But, it may be redundant for you because of the many of installed pecl-extensions, _(*37)

Storages comparison

Redis is the best key-value storage for cache. Use Couchbase if you need fault-tolerant and very easy scalable cluster and if you can afford it (recommended hardware requirements). Also, data in Redis and Couchbase storages will be restored even after server reboot., _(*38)

Differences between the approaches a tagging

Grouping tags

Fastest method, but there is a possibility of overflow cache., _(*39)

Set a value:, _(*40)

$cache = new \rock\cache\Memcached;

$cache->set('key_1', 'text_1', 0, ['tag_1', 'tag_2']);
$cache->set('key_2', 'text_2', 0, ['tag_1']);

View in memory:, _(*41)

key_1: text_1
key_2: text_2

tag_1: [key_1, key_2]
tag_2: [key_1]

Removing tag:, _(*42)

$cache->removeTag('tag_2');

View in memory:, _(*43)

key_2: text_2

tag_1: [key_1, key_2]

Versioning tags

Is the best practice, but slower than the approach with the grouping tags, because when getting the cache containing tags, sent multiple requests to compare versions. There is no cache overflows., _(*44)

References: nablas by D.Koterov (RUS) or "Reset group caches and tagging" by A.Smirnov (RUS)., _(*45)

Set a value:, _(*46)

$cache = new \rock\cache\versioning\Memcached;

$cache->set('key_1', 'text_1', 0, ['tag_1', 'tag_2']);
$cache->set('key_2', 'text_2', 0, ['tag_1']);

View in memory:, _(*47)

key_1: [
    value : text_1,
    tags : [
        tag_1 : 0.20782200 1403858079,
        tag_2 : 0.20782200 1403858079
    ]
]
// tag : microtime

key_2: [
    value : text_2,
    tags : [
        tag_1 : 0.20782200 1403858079,
    ]
]

tag_1: 0.20782200 1403858079
tag_2: 0.20782200 1403858079

Removing tag:, _(*48)

$cache->removeTag('tag_2');

View in memory:, _(*49)

key_1: [
    value : text_1,
    tags : [
        tag_1 : 0.20782200 1403858079,
        tag_2 : 0.20782200 1403858079
    ]
]
key_2: [
    value : text_2,
    tags : [
        tag_1 : 0.20782200 1403858079,
    ]
]

tag_1: 0.20782200 1403858079
tag_2: 0.29252400 1403858537

Returns value:, _(*50)

$cache->get('key_1');
// result: false

View in memory:, _(*51)

key_2: [
    value : text_2,
    tags : [
        tag_1 : 0.20782200 1403858079,
    ]
]

tag_1: 0.20782200 1403858079

License

The Rock Cache library is open-sourced software licensed under the MIT license, _(*52)