nlmdev/hoard

A PSR-compliant caching library for holding objects in nested pools with scripting ability.

Hoard

What Is It?

Hoard is a caching library., _(*1)

Hoard's goal are:, _(*2)

• To be totally independant from any other framework.
• To be PSR-6: Cache (more information here) compliant so that it should work with any modern framework.
• Support multiple adapters for storage (like memcached).
• Support multiple discreet pools, and nested pools.
• Provide a way to automate actions with a script that is easy to use and version controlled with the application.
• A command line utility to run these scripts.

Basic Usage

Pools are Classes

You may follow the PSR-6 standard explicitely for getting and setting items in the cache. However there are some code requirements for you to be able to create the physical pool., _(*3)

Each pool is represented by a concrete class that extends \Hoard\AbstractPool. Nested pools will be class that extend their parent pool class, not \Hoard\AbstractPool., _(*4)

Pool names translate directly and both ways between the class name. With the following examples (pool name => class name):, _(*5)

• my_pool => MyPool
• parent.child_pool => Parent\ChildPool

Pools are located in a specific namespace provided by \Hoard\CacheManager::getNamespace(), which as of the writing of this document, is \Hoard\Hoard\Pool. Extending from the above examples;, _(*6)

• my_pool => \HoardPool\MyPool
• parent.child_pool => \HoardPool\Parent\ChildPool

Never instantiate the classes themselfs. You must use the CacheManager to retrieve the pool instances., _(*7)

try {
    $pool = \Hoard\CacheManager::getPool('my.pool');
}
catch(\Hoard\NoSuchPoolException $e) {
    // deal with this appropriately
}

Storing and Retrieving

Once you have the pool instance (from the previous example), you can:, _(*8)

$item = $pool->getItem('key');
if($item->isHit()) {
    echo "Got: {$item->get()}";
}
else {
    echo "Item {$item->getKey()} is not in the cache.";
}

Regardless of whether the item was stored in the cache previously, you save data to the cache the same way:, _(*9)

$item->set('myvalue')

There is an optional second argument for set() that allows you to specify a expiry time:, _(*10)

These will never expire (default):, _(*11)

$item->set('myvalue');
$item->set('myvalue', null);

This will expire in 1 hour from now:, _(*12)

$item->set('myvalue', 3600);

This will expire at the specific timestamp:, _(*13)

$item->set('myvalue', new \DateTime('4th March 2015'));

Clearing Cache

To delete a single item from a pool:, _(*14)

$pool->getItem('key')->delete();

You may want to drop an entire pool:, _(*15)

$pool->clear();

Using a Cache Script

A hoard script is just a text file (the extension is not important, although .txt is the easiest to use) which specifies targets and commands that can be run from a command line utility., _(*16)

The syntax is similar to a Makefile, targets have dependencies, except that indentation can be any white space before a command., _(*17)

Run targets like you would a Makefile, through the ./g script:, _(*18)

./g hoard mytarget

Syntax

Pool names are important because they link directly to concrete classes, trying to perform any action on a pool that doesn't exist will result in an exception (the script will stop execution and return a non 0 exit code)., _(*19)

Drop an entire pool (and all of its child pools):, _(*20)

drop my.pool_name

Drop individual keys inside a pool:, _(*21)

drop my.pool:key1,key2,key3

Comments are any line, or part of a line that comes after a #:, _(*22)

# this is a comment
drop my.pool_name # this is also fine

Full Example

# my cool script
safe_drop:
    # this are items that may be safely dropped at any time and should be
    # dropped with any change to the software
    drop page:homepage

release: safe_drop
    # should be run with every production release

Running the release target like this:, _(*23)

$ ./g hoard release
Running target 'safe_drop'
  drop page:homepage... Done
Success.
Running target 'release'
  Nothing to do.
Success.

The ./g hoard command runs the script located at install-script/hoard.txt., _(*24)

Mocking a Pool

There is a \Hoard\PoolTestCase you can use to generate mocked pools that have prepopulated data. This is easier than trying to do it in other ways., _(*25)

class MyTest extends \Hoard\PoolTestCase
{

    public function testMockingPool()
    {
        // create mock
        $pool = $this->getMockedPool(array(
            'mykey' => 'myvalue'
        ));

        // found item
        $item = $pool->getItem('mykey');
        $this->assertEquals($item->get(), 'myvalue');
        $this->assertTrue($item->isHit());

        // not found item
        $item = $pool->getItem('mykey2');
        $this->assertFalse($item->isHit());
    }

}

Modified to add options to Memcached

Added code that sets the value of a Memcached option. Some options correspond to the ones defined by libmemcached, and some are specific to the extension. See Memcached Constants for more information., _(*26)