README.md

======= Molajo Cache API

Simple, clean cache API for PHP applications to get, [set] (https://github.com/Molajo/Cache/Cache#set), [remove] (https://github.com/Molajo/Cache/Cache#remove), [clear] (https://github.com/Molajo/Cache/Cache#clear), cache.

Cache Handlers available include:

• Apc,
• Database,
• Dummy,
• File,
• Memcached,
• Memory,
• Redis,
• Wincache, and
• xCache.

At a glance ...

1. Construct a Cache Handler Class.
2. Instantiate the Cache Adapter, injecting it with the Cache Handler instance.
3. Set cache.
4. Get cache.
5. Remove cache.
6. Clear cache.

    // 1. Instantiate a Cache Handler.
    $options = array();
    $options['cache_folder']  = SITE_BASE_PATH . '/' . $application->get('system_cache_folder', 'cache');
    $options['cache_time']    = $application->get('system_cache_time', 900);
    $options['cache_handler'] = $application->get('cache_handler', 'File');

    use Molajo\Cache\Adapter\File as FileCache;
    $adapter_handler = new FileCache($options);

    // 2. Instantiate the Adapter, injecting it with the Handler.
    use Molajo\Cache\Adapter;
    $adapter = new Driver($adapter_handler);

    // 3. Set cache.
    $adapter->set('key value', 'cache this value for seconds =>', 86400);

    // 4. Get Cache.
    $cacheItem = $adapter->get('this is the key for a cache item');

    if ($cacheItem->isHit() === false) {
        // deal with no cache
    } else {
        echo $cacheItem->value; // Use the Cached Value
    }

    // 5. Remove cache.
    $adapter->remove('key value');

    // 6. Clear cache.
    $adapter->clear();

Cache API

Common API for Cache operations: get, [set] (https://github.com/Molajo/Cache/Cache#set), [remove] (https://github.com/Molajo/Cache/Cache#remove), [clear] (https://github.com/Molajo/Cache/Cache#clear) methods.

Get

Retrieves a CacheItem object associated with the key. If the value is not found, an exception is thrown.

    try {
        $cacheItem = $adapter->get($key);

    } catch (Exception $e) {
        // deal with the exception
    }

    if ($cacheItem->isHit() === true) {
        $cached_value = $cacheItem->getValue();
    } else {
        // cache is not available - do what you have to do.
    }

Parameters

• $key contains the key value for the requested cache

Set

Stores a value as cache for the specified Key value and number of seconds specified.

    try {
        $adapter->set($key, $value, $ttl);

    } catch (Exception $e) {
        // deal with the exception
    }

Parameters

• $key contains the value to use for the cache key
• $value contains the value to be stored as cache
• $ttl "Time to live" which is the number of seconds the cache is considered relevant

Remove

Removes a cache entry associated with the specified Key value.

    try {
        $adapter->remove($key);

    } catch (Exception $e) {
        // deal with the exception
    }

Parameters

• $key contains the value to use for the cache key

Clear

Remove all cache for this Cache Handler instance.

    try {
        $adapter->clear();

    } catch (Exception $e) {
        // deal with the exception
    }

Parameters

• n/a no parameters are required

Cache Adapter Handlers

Cache Handlers available include:

• Apc,
• Database,
• Dummy,
• File,
• Memcached,
• Memory,
• Redis,
• Wincache, and
• xCache.

Apc

APC (Alternative PHP Cache) comes standard with PHP. An APC Cache Handler is available with Molajo Cache and can be used, as follows.

    $options = array();

    // Standard Cache Options
    $options['cache_service']       = 1;
    $options['cache_time']          = 86400;

    // Instantiate Cache Handler
    use Molajo\Cache\Adapter\Apc;
    $adapter_handler = new Apc($options);

    // Instantiate Cache Adapter, injecting the Handler
    use Molajo\Cache\Adapter;
    $adapter = new Driver($adapter_handler);

Database

Before using the Database Cache Handler, a table must be available with four columns: id (identity column), key (varchar(255)), value (text) and expiration (integer). When instantiating the Cache Handler, pass in the database connection, the name of the database table for cache, the value for the RDBMS quote and name quote, as shown in this example.

    $options = array();

    // Standard Cache Options
    $options['cache_service']       = 1;
    $options['cache_time']          = 86400;

    // Specific to the Database Handler
    $options['database_connection'] = $connection;
    $options['database_table']      = 'xyz_cache_table';
    $options['database_quote']      = "'";
    $options['database_namequote']  = '`';

    // Instantiate Cache Handler
    use Molajo\Cache\Adapter\Database;
    $adapter_handler = new Database($options);

    // Instantiate Cache Adapter, injecting the Handler
    use Molajo\Cache\Adapter;
    $adapter = new Driver($adapter_handler);

Dummy

The Dummy Cache Handler can be used for testing purpose. It does not really cache data. Use, as follows:

    $options = array();

    // Standard Cache Options
    $options['cache_service']       = 1;
    $options['cache_time']          = 86400;

    // Instantiate Cache Handler
    use Molajo\Cache\Adapter\Dummy as DummyCache;
    $adapter_handler = new DummyCache($options);

    // Instantiate Cache Adapter, injecting the Handler
    use Molajo\Cache\Adapter;
    $adapter = new Driver($adapter_handler);

File

The File Cache Handler can be used to turn the local filesystem into a caching device. Use, as follows:

    $options = array();

    // Standard Cache Options
    $options['cache_service']       = 1;
    $options['cache_time']          = 86400;

    // Specific to the File Handler
    $options['cache_handler']       = '/Absolute/Path/To/Cache/Folder';

    // Instantiate Cache Handler
    use Molajo\Cache\Adapter\File as FileCache;
    $adapter_handler = new FileCache($options);

    // Instantiate Cache Adapter, injecting the Handler
    use Molajo\Cache\Adapter;
    $adapter = new Driver($adapter_handler);

Memcached

The Memcached Cache Handler requires the memcached PHP extension be loaded and that the Memcached class exists. For more information, see Memcached in the PHP Manual. Use, as follows:

    $options = array();

    // Standard Cache Options
    $options['cache_service']       = 1;
    $options['cache_time']          = 86400;

    // Specific to the Memcached Handler
    $options['memcached_pool']         = $connection;
    $options['memcached_compression']  = 'xyz_cache_table';
    $options['memcached_servers']      = "'";

    // Instantiate Cache Handler
    use Molajo\Cache\Adapter\Memcached
    $adapter_handler = new Memcached($options);

    // Instantiate Cache Adapter, injecting the Handler
    use Molajo\Cache\Adapter;
    $adapter = new Driver($adapter_handler);

Memory

The Memory Cache Handler can be used storing the variables in memory. This can be used with Sessions to create persistence, if desired. Use, as follows:

    $options = array();

    // Standard Cache Options
    $options['cache_service']       = 1;
    $options['cache_time']          = 86400;

    // Instantiate Cache Handler
    use Molajo\Cache\Adapter\Memory
    $adapter_handler = new Memory($options);

    // Instantiate Cache Adapter, injecting the Handler
    use Molajo\Cache\Adapter;
    $adapter = new Driver($adapter_handler);

Redis

The Redis Cache Handler can be used storing the variables in memory. This can be used with Sessions to create persistence, if desired. Use, as follows:

    $options = array();

    // Standard Cache Options
    $options['cache_service']       = 1;
    $options['cache_time']          = 86400;

    // Instantiate Cache Handler
    use Molajo\Cache\Adapter\Redis
    $adapter_handler = new Redis($options);

    // Instantiate Cache Adapter, injecting the Handler
    use Molajo\Cache\Adapter;
    $adapter = new Driver($adapter_handler);

Wincache

The Wincache Cache Handler requires the PHP extension wincache is loaded and that wincache_ucache_get is callable. For more information, see Windows Cache for PHP.. Besides using the Windows Operating System, there are no other configuration options required to use Wincache.

    $options = array();

    // Standard Cache Options
    $options['cache_service']       = 1;
    $options['cache_time']          = 86400;

    // Instantiate Cache Handler
    use Molajo\Cache\Adapter\Wincache
    $adapter_handler = new Wincache($options);

    // Instantiate Cache Adapter, injecting the Handler
    use Molajo\Cache\Adapter;
    $adapter = new Driver($adapter_handler);

xCache

The xCache Handler requires the PHP extension xcache is loaded and that xcache_get is callable.

    $options = array();

    // Standard Cache Options
    $options['cache_service']       = 1;
    $options['cache_time']          = 86400;

    // Instantiate Cache Handler
    use Molajo\Cache\Adapter\XCache
    $adapter_handler = new XCache($options);

    // Instantiate Cache Adapter, injecting the Handler
    use Molajo\Cache\Adapter;
    $adapter = new Driver($adapter_handler);

Install using Composer from Packagist

Step 1: Install composer in your project

    curl -s https://getcomposer.org/installer | php

Step 2: Create a composer.json file in your project root

{
    "require": {
        "Molajo/Cache": "1.*"
    }
}

Step 3: Install via composer

    php composer.phar install

Requirements and Compliance

• PHP framework independent, no dependencies
• Requires PHP 5.4, or above
• Semantic Versioning
• Compliant with:
  • PSR-0 and PSR-1 Namespacing
  • PSR-2 Coding Standards
  • PSR-Cache Interfaces (Still in Draft)
• [phpDocumentor2] (https://github.com/phpDocumentor/phpDocumentor2)
• [phpUnit Testing] (https://github.com/sebastianbergmann/phpunit)
• Author AmyStephen
• [Travis Continuous Improvement] (https://travis-ci.org/profile/Molajo)
• Listed on [Packagist] (http://packagist.org) and installed using [Composer] (http://getcomposer.org/)
• Use github to submit pull requests and features
• Licensed under the MIT License - see the LICENSE file for details