###CLASS INSTANTIATION

The minimum you need to get RedisCache up and running is:

```php
$redis = new \RedisCache(array('port' => 8379, 'redis_host'=>'{your_redis_server}'));
```
Note: The host variable is named `redis_host`. This is to distinguish it from an internal redis class property called `host`.

###SETTING KEYS AND DATA

All data in redis is stored in key-value data pairs. In most circumstances, a key will be hashed and namespaced. A sample key might look something like this:

```
host:phpunit-1|key:0738b6cf958c0644c99b3ff1223e8137
```

The key has two parts: a host and a hashed key. The hash can be made from a string, integer, or an array. Most likely the key hash will be made from an array of parameters passed in through VAPI.

To save data to a key, the following call is made:

```php
$redis->setHost('myhost')
	  ->setKey('my_params')
	  ->setData('my_data')
	  ->save();
```

First the host is set, then key is set, then the data is set, and then the object is saved.

All setters are chainable. In most cases you will not need to set the host, since the host is done internally. So, a more realistic call might be:

```php
$redis->setKey('my_params')
	  ->setData('my_data')
	  ->save();
```

###GETTING KEYS AND DATA

If you would like to retrieve a key string with no data, you can do any of the following, depending on context:

```php
//explicitly set all values
$redis->setHost('myhost')
	  ->setKey('my_params')
	  ->getKey();
//use object's current values
$redis->setKey('my_params')->getKey();
```

To retrieve data for a key, you can use any of the following:

```php
//explicitly set all values
$redis->setHost('myhost')
	  ->setKey('my_params')
	  ->get();
//use object's current values
$redis->setKey('my_params')->get();
```

The `get` method will returned the cached data only (i.e whatever was passed to `setData`). If you want do also retrieve the cache's metadata, use the `getFull` method:

```php
//explicitly set all values
$redis->setHost('myhost.com')
	  ->setKey('my_params')
	  ->getFull();
//use object's current values
$redis->setKey('my_params')->getFull();
```

This will return json of the entire cache object, plus available meta keys. A sample response might look something like this:

```
 {
 	"id": "host:myhost.com|vendor:123|key:acbd18db4cc2f85cedef654fccc4a4d8",
 	"data": "my_data",
 	"host": "myhost.com",
 	"tags": [
 		"tag_1",
 		"tag_2",
 		"tag_3"
 	],
 	"params": "my_params",
 	"ttl": 86400,
 	"expire": "1375460711",
 	"expire_date": "2013-08-02 06:25:11 pm"
}
```

A breakdown:

* `id`: The full key
* `data`: The data stored. This is what is returned by `get`
* `host`: Host that set the data.
* `tags`: Array of all tags associated with the record.
* `params`: Original unhashed value sent to `setKey`
* `ttl`: Time to live in seconds from the creation of the record.
* `expire`: Timestamp of when the key will expire.
* `expire_date`: When, in human-readable form, the key will expire.

Finally, counts can be retrieved for most sets. For example, to count the set for host.com:

```php
$redis->setHost('host.com')
	  ->getCount();
```

Or for all keys in the database:

```php
$redis->setHost(null)
	  ->getCount();
```

You can also search for keys without creating a key. For example, if you were to do the following:

```php
$redis->setKey('test')
	  ->getKey()
```

Something like the following would be returned:

```
host:myhost.com|key:acbd18db4cc2f85cedef654fccc4a4d8
```

However, if all you have is that second, transformed key, the following attempt to retrieve the cache's associated key will *not* work:

```
$redis->setKey('host:myhost.com|vendor:123|key:acbd18db4cc2f85cedef654fccc4a4d8')
	  ->get()
```

This is because the key will be transformed (hashed) twice, thus giving unexpected results. Instead, you can use the `useLiteralKey` method:

```php
$redis->useLiteralKey()
	  ->setKey('host:myhost.com|vendor:123|key:acbd18db4cc2f85cedef654fccc4a4d8')
	  ->get()
```

CAVEAT: If you do the above, the object is now set to use only literal keys. To set it back, use `useHashKey`:

```php
$redis->useHashKey()
	  ->setKey('test')
	  ->get()
```

###TAGS

Each key-value pair can be associated with tags. Tags are strings that can be used to track various kinds of keys. The number of tags is unlimited, though each tag adds some overhead to set and delete methods, so use tags sparingly. 

Some typical use cases might be tracking cache items by vendor id or by resource. So, for example:

```php
$redis->setTags(array('vendor_123', 'factsales/index'))
	  ->setKey('123')
	  ->setData('456')
	  ->save();
```

This key will now be associated with `vendor_123` and `factsales/index`. In order to find all keys associated with `vendor_123` for the current host, use:

```php
$redis->getByTag('vendor_123');
```

###PARSING A URI AND SETTING A KEY

Most keys will be created from uri's like the following:

```
http://myvector.theorchard.com/vectorapi/salesbreakdown/?viewBy=releaseId&page=1&limit=10&fromAccountingPeriodId=170&toAccountingPeriodId=171&labelIds=8869&offset=0&isSubaccount=0&data_format=json&access_token=f9ab5b4fe1a5e9e48f9ec0d069e8d7d1&statement=1&formatCurrency=1
```

In order to use this uri as a key, you must use two commands:

```php
$parts = $redis->parseUri($uri, array('viewBy', 'limit' ... ));
$redis->setKey($parts);
```

The first method parses the uri into key-value pairs for each parameter. The first argument is a string holding the uri. The second argument is a list of 'safe' query parameters. This is used in order to prevent accidental or malicious cache busting. 

RedisCacge will also add a parameter, `path`, which includes the path ('/vectorapi/salesbreakdown' in the above example) without a trailing slash. The host is ignored.

If no safe parameters are provided, only a path will be returned.

In the second line, the `setKey` method alphabetically sorts the array and lowercases the keys. It then hashes them and assembles the key.

In some edge cases, one does not want to use safeParams, to do so, use:

```php
$redis->ignoreSafeParams()
	  ->parseUri($uri)
```

As with `useLiteralKey`, you have to turn the `ignoreSafeParams` off if you want the next call to use safeParams:

```php
$redis->useSafeParams()
	  ->parseUri($uri)
```

###GETTING AND SETTING GOTCHAS

* Data cannot be set to false. It will be saved as a 0 instead. This is because...
* A key that does not exist returns false.

###DELETING KEYS

Deleting a single key is a simple operation. As above, chain your settings for the key, but end the call with `del`:

```php
$redis->setKey('foo')
	  ->del();
```

You can also delete keys for an entire host. This can get expensive, so it is probably best to do it only in certain rare admin use cases:

```php
//delete all keys for a host
$redis->setHost('host.com')
	  ->delHost();
```

If you would like to investigate which keys were deleted by the above operation, use the following:

```php
$redis->setHost('host.com')
	  ->delHost();
$redis->getKeysDeleted();
$redis->getKeysNotDeleted();
```


###EXPIRATION OF DATA

All keys come with expiration times. All expiration times are in seconds. So, to expire a record five seconds from now `setExpire` should be set to 5. The default expiration is one day: 86400 seconds.

An example expiration:

```php
//set data to expire in one minute
$redis->setExpire(60)
	  ->setKey('foo')
	  ->setData('bar');
```

As of this writing, expired keys will exist in the database until they are retrieved. If an expired key is retrieved it is immediately deleted and false is returned.

In order to get the ttl of the record, use the following:

```php
$redis->setKey('foo')->ttl();
```

And to get the expire time:

```php
$redis->setKey('foo')->getExpire();
```

###META KEYS

Redis maintains several internal keys that act as 'meta' keys. These keys stories sorted sets of keys. For example the 'keys' metakey is a set of all the keys in the database. There are three top-level meta keys:

* `keys`: All keys in the database, excluding meta keys.
* `hosts`: All hosts in the database.
* `host:{host_name}|keys`: All keys for a particular host. 
* `vendor:{host_name}|keys`: All keys for a particular vendor.

One of the Redis class's functions is to manage these sorted sets. Without these sets, no structured queries could be made against the overall superset of keys.

To see a list of all vendor or hosts, use the following:

```php
//get a list of all hosts, where {start} and {stop} slice the array (defaults to 0, 24)
$redis->getHosts({start}, {stop});

//get a count of all hosts
$redis->getHostsCount();

//get all keys for the db, where {start} and {stop} slice the array (defaults to 0, 24)
$redis->setHost(null)->getMany({start}, {stop});

//get all keys for host.com, where {start} and {stop} slice the array (defaults to 0, 24)
$redis->setHost('host.com')->getMany({start}, {stop});
```

Note: `getMany` aliases to `getKeys` and `getOne` aliases to `get`

###OTHER USEFUL METHODS

The entire redis object can be switched off, if necessary. The calls to do so are `activate` and `deactivate`. To check to see if the object is active anywhere in the code, use `isActive` (returns boolean).

If the object is deactivated, all public methods will return `false`.

To check to see if a dev environment has the redis module and the server is responding, use `hasRedis` (returns boolean).