Koded - Simple Caching Library

A PSR-16 simple caching library for PHP 7 using several caching technologies. It supports JSON caching for Redis.

Requirements

The library is not tested on any Windows OS and may not work as expected there.

Redis

There are two client flavors for Redis by using the

• Redis extension
• Predis library

and they are not mutually exclusive.

These clients supports JSON serialization for your cache, useful if you want to handle the cached data in other programming languages.

Since there is no Redis native support for JSON serialization, it's done in userland and that always introduces some overhead. Be aware that the native PHP and Igbinary serializers are superior.

• the RedisClient is preferred if you install the Redis extension
• the PredisClient can be used otherwise

// with Redis extension
simple_cache_factory('redis');

// with Predis library
simple_cache_factory('predis');

Memcached

Please install the Memcached extension.

Usage

Install the library from Packagist with Composer.

composer require koded/cache-simple

The factory function always creates a new instance of specific SimpleCacheInterface client implementation.

/*
 * Creates a simple cache instance
 * with MemcachedClient and default configuration
 */

$cache = simple_cache_factory('memcached');

/*
 * Some configuration directives for the cache client
 * are passed in the second argument as array
 */

$cache = simple_cache_factory('redis', [
    'host'       => '127.0.0.1',
    'serializer' => 'json',
    'prefix'     => 'test:',
    'ttl'        => 3600 // 1 hour global TTL
]);

A bit verbose construction for the same instance is

$config = new ConfigFactory(['serializer' => 'json', 'prefix' => 'test:', 'ttl' => 3000]);
$cache = (new CacheClientFactory($config))->new('redis');

Configuration directives

Current available configuration classes

• RedisConfiguration
• MemcachedConfiguration
• FileConfiguration
• PredisConfiguration

RedisConfiguration

Please refer to Redis extension connect method.

Parameter	Value
host	127.0.0.1
port	6379
timeout	0.0
reserved	null
retry	0

// Without defining the parameters the above directives are used as default
$cache = simple_cache_factory('redis');

Serializers

• php (default)
• json

The special config directive is binary(string) for setting the internal serializer functions to either PHP native un/serialize(), igbinary_un/serialize() or msgpack_un/pack().

$cache = simple_cache_factory('redis', [
    'binary' => \Koded\Stdlib\Interfaces\Serializer::MSGPACK
]);

The binary directive is effective if igbinary and/or msgpack extensions are installed and loaded. Otherwise it defaults to PHP un/serialize() functions.

You can change the binary flag on already cached data, but you should invalidate the previously cached items, since they are already serialized and stored in the cache.

JSON serializer options

The default options for json_encode() function are:

• JSON_PRESERVE_ZERO_FRACTION
• JSON_UNESCAPED_SLASHES

To set your desired options, use the options configuration directive:

$cache = simple_cache_factory('redis', [
    'serializer' => 'json',
    'options' => JSON_UNESCAPED_SLASHES | JSON_FORCE_OBJECT
]);

MemcachedConfiguration

Memcached arguments	Type	Required	Description
id	string	no	Memcached persistent_id value
servers	array	no	A list of nested array with [server, port] values
options	array	no	A list of Memcached options
ttl	int	no	Global TTL (in seconds)

The following options are set by default when instance of MemcachedConfiguration is created, except for OPT_PREFIX_KEY which is there as a reminder that it may be set

Memcached option	Default value
OPT_DISTRIBUTION	DISTRIBUTION_CONSISTENT
OPT_SERVER_FAILURE_LIMIT	2
OPT_REMOVE_FAILED_SERVERS	true
OPT_RETRY_TIMEOUT	1
OPT_LIBKETAMA_COMPATIBLE	true
OPT_PREFIX_KEY	null

Options with value NULL will be removed.

There are many Memcached options that will suit the specific needs for your caching scenarios and this is something you need to figure it out by yourself.

Examples:

[
    // Memcached client `persistent_id`
    'id' => 'items',

    // your Memcached servers list
    'servers' => [
        ['127.0.0.1', 11211],
        ['127.0.0.2', 11211],
        ['127.0.0.2', 11212],
    ],

    // Memcached client options
    'options' => [
        \Memcached::OPT_PREFIX_KEY            => 'i:',  // item prefix
        \Memcached::OPT_REMOVE_FAILED_SERVERS => false, // change the default value
        \Memcached::OPT_DISTRIBUTION          => null   // remove this directive
    ],

    // the global expiration time (for ALL cached items)
    'ttl' => 120,
]

PredisConfiguration

By default the parameters are:

Parameter	Value
scheme	tcp
host	127.0.0.1
port	6379

Examples:

$cache = simple_cache_factory('predis');

$cache = simple_cache_factory('predis', [
    'scheme' => 'unix',
    'path' => '/path/to/redis.sock',
    'options' => [
        'prefix' => 'i:',
        'exceptions' => true,
        'parameters' => [
            'password' => getenv('REDIS_PASSWORD'),
            'database' => 1
        ]
    ]
]);

There are many configuration options for this package. Please refer to Predis configuration page.

Shared Memory (shmop)

Requires a PHP shmop extension.

$cache = simple_cache_factory('shmop', [
    'dir' => '/path/to/app/cache', // optional
    'ttl' => null,                 // global TTL
]);

FileConfiguration

This is the slowest cache client, please avoid it for production environments.

If you do not provide the cache directory in the configuration, the PHP function sys_get_temp_dir() is used to store the cached files.

$cache = simple_cache_factory('file', ['dir' => '/tmp']);

MemoryClient

This client will store the cached items in the memory for the duration of the script's lifetime. It is useful for development, but not for production.

MemoryClient is also the default client if you do not require a specific client in cache_simple_factory()

$cache = simple_cache_factory('memory');
$cache = simple_cache_factory();  // also creates a MemoryClient

License

The code is distributed under the terms of The 3-Clause BSD license.