Caching Driver
**************

CodeIgniter features wrappers around some of the most popular forms of
fast and dynamic caching. All but file-based caching require specific
server requirements, and a Fatal Exception will be thrown if server
requirements are not met.

* Example Usage

* Class Reference

* Drivers

  * Alternative PHP Cache (APC) Caching

  * File-based Caching

  * Memcached Caching

  * WinCache Caching

  * Redis Caching

  * Dummy Cache

Example Usage
=============

The following example will load the cache driver, specify APC as the
driver to use, and fall back to file-based caching if APC is not
available in the hosting environment.

   $this->load->driver('cache', array('adapter' => 'apc', 'backup' => 'file'));

   if ( ! $foo = $this->cache->get('foo'))
   {
           echo 'Saving to the cache!
';
           $foo = 'foobarbaz!';

           // Save into the cache for 5 minutes
           $this->cache->save('foo', $foo, 300);
   }

   echo $foo;

You can also prefix cache item names via the **key_prefix** setting,
which is useful to avoid collisions when you’re running multiple
applications on the same environment.

   $this->load->driver('cache',
           array('adapter' => 'apc', 'backup' => 'file', 'key_prefix' => 'my_')
   );

   $this->cache->get('foo'); // Will get the cache entry named 'my_foo'


Class Reference
===============

class CI_Cache

   is_supported($driver)

      Parameters:
         * **$driver** ("string") – the name of the caching driver

      Returns:
         TRUE if supported, FALSE if not

      Return type:
         "bool"

      This method is automatically called when accessing drivers via
      "$this->cache->get()". However, if the individual drivers are
      used, make sure to call this method to ensure the driver is
      supported in the hosting environment.

         if ($this->cache->apc->is_supported())
         {
                 if ($data = $this->cache->apc->get('my_cache'))
                 {
                         // do things.
                 }
         }

   get($id)

      Parameters:
         * **$id** ("string") – Cache item name

      Returns:
         Item value or FALSE if not found

      Return type:
         "mixed"

      This method will attempt to fetch an item from the cache store.
      If the item does not exist, the method will return FALSE.

         $foo = $this->cache->get('my_cached_item');

   save($id, $data[, $ttl = 60[, $raw = FALSE]])

      Parameters:
         * **$id** ("string") – Cache item name

         * **$data** ("mixed") – the data to save

         * **$ttl** ("int") – Time To Live, in seconds (default 60)

         * **$raw** ("bool") – Whether to store the raw value

      Returns:
         TRUE on success, FALSE on failure

      Return type:
         "string"

      This method will save an item to the cache store. If saving
      fails, the method will return FALSE.

         $this->cache->save('cache_item_id', 'data_to_cache');

      Note:

        The "$raw" parameter is only utilized by APC and Memcache, in
        order to allow usage of "increment()" and "decrement()".

   delete($id)

      Parameters:
         * **$id** ("string") – name of cached item

      Returns:
         TRUE on success, FALSE on failure

      Return type:
         "bool"

      This method will delete a specific item from the cache store. If
      item deletion fails, the method will return FALSE.

         $this->cache->delete('cache_item_id');

   increment($id[, $offset = 1])

      Parameters:
         * **$id** ("string") – Cache ID

         * **$offset** ("int") – Step/value to add

      Returns:
         New value on success, FALSE on failure

      Return type:
         "mixed"

      Performs atomic incrementation of a raw stored value.

         // 'iterator' has a value of 2

         $this->cache->increment('iterator'); // 'iterator' is now 3

         $this->cache->increment('iterator', 3); // 'iterator' is now 6

   decrement($id[, $offset = 1])

      Parameters:
         * **$id** ("string") – Cache ID

         * **$offset** ("int") – Step/value to reduce by

      Returns:
         New value on success, FALSE on failure

      Return type:
         "mixed"

      Performs atomic decrementation of a raw stored value.

         // 'iterator' has a value of 6

         $this->cache->decrement('iterator'); // 'iterator' is now 5

         $this->cache->decrement('iterator', 2); // 'iterator' is now 3

   clean()

      Returns:
         TRUE on success, FALSE on failure

      Return type:
         "bool"

      This method will ‘clean’ the entire cache. If the deletion of
      the cache files fails, the method will return FALSE.

         $this->cache->clean();

   cache_info()

      Returns:
         Information on the entire cache database

      Return type:
         "mixed"

      This method will return information on the entire cache.

         var_dump($this->cache->cache_info());

      Note:

        The information returned and the structure of the data is
        dependent on which adapter is being used.

   get_metadata($id)

      Parameters:
         * **$id** ("string") – Cache item name

      Returns:
         Metadata for the cached item

      Return type:
         "mixed"

      This method will return detailed information on a specific item
      in the cache.

         var_dump($this->cache->get_metadata('my_cached_item'));

      Note:

        The information returned and the structure of the data is
        dependent on which adapter is being used.


Drivers
=======


Alternative PHP Cache (APC) Caching
-----------------------------------

All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows:

   $this->load->driver('cache');
   $this->cache->apc->save('foo', 'bar', 10);

For more information on APC, please see http://php.net/apc.


File-based Caching
------------------

Unlike caching from the Output Class, the driver file-based caching
allows for pieces of view files to be cached. Use this with care, and
make sure to benchmark your application, as a point can come where
disk I/O will negate positive gains by caching.

All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows:

   $this->load->driver('cache');
   $this->cache->file->save('foo', 'bar', 10);


Memcached Caching
-----------------

Multiple Memcached servers can be specified in the memcached.php
configuration file, located in the _application/config/* directory.

All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows:

   $this->load->driver('cache');
   $this->cache->memcached->save('foo', 'bar', 10);

For more information on Memcached, please see
http://php.net/memcached.


WinCache Caching
----------------

Under Windows, you can also utilize the WinCache driver.

All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows:

   $this->load->driver('cache');
   $this->cache->wincache->save('foo', 'bar', 10);

For more information on WinCache, please see http://php.net/wincache.


Redis Caching
-------------

Redis is an in-memory key-value store which can operate in LRU cache
mode. To use it, you need Redis server and phpredis PHP extension.

Config options to connect to redis server must be stored in the
application/config/redis.php file. Available options are:

   $config['socket_type'] = 'tcp'; //`tcp` or `unix`
   $config['socket'] = '/var/run/redis.sock'; // in case of `unix` socket type
   $config['host'] = '127.0.0.1';
   $config['password'] = NULL;
   $config['port'] = 6379;
   $config['timeout'] = 0;

All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows:

   $this->load->driver('cache');
   $this->cache->redis->save('foo', 'bar', 10);

For more information on Redis, please see http://redis.io.


Dummy Cache
-----------

This is a caching backend that will always ‘miss.’ It stores no data,
but lets you keep your caching code in place in environments that
don’t support your chosen cache.
