Merge branch 'develop' of github.com:EllisLab/CodeIgniter into develop

1 files changed, 220 insertions, 0 deletions

diff --git a/user_guide_src/source/libraries/caching.rst b/user_guide_src/source/libraries/caching.rst
new file mode 100644
index 000000000..2f06d29f9
--- /dev/null
+++ b/user_guide_src/source/libraries/caching.rst
@@ -0,0 +1,220 @@
+##############
+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.
+
+.. contents:: Table of Contents
+
+*************
+Example Usage
+*************
+
+The following example will load the cache driver, specify `APC <#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!<br />';
+		$foo = 'foobarbaz!';
+		
+		// Save into the cache for 5 minutes
+		$this->cache->save('foo', $foo, 300);
+	}
+	
+	echo $foo;
+
+******************
+Function Reference
+******************
+
+.. php:class:: CI_Cache
+
+is_supported()
+===============
+
+	.. php:method:: is_supported ( $driver )
+
+		This function is automatically called when accessing drivers via
+		$this->cache->get(). However, if the individual drivers are used, make
+		sure to call this function to ensure the driver is supported in the
+		hosting environment.
+		
+		:param string $driver: the name of the caching driver
+		:returns: TRUE if supported, FALSE if not
+		:rtype: Boolean
+		
+		::
+				
+			if ($this->cache->apc->is_supported()
+			{
+				if ($data = $this->cache->apc->get('my_cache'))
+				{
+					// do things.
+				}
+			}
+
+
+get()
+=====
+
+	.. php:method:: get ( $id )
+	
+		This function will attempt to fetch an item from the cache store. If the
+		item does not exist, the function will return FALSE.
+
+		:param string $id: name of cached item
+		:returns: The item if it exists, FALSE if it does not
+		:rtype: Mixed
+		
+		::
+
+			$foo = $this->cache->get('my_cached_item');
+
+
+save()
+======
+
+	.. php:method:: save ( $id , $data [, $ttl])
+	
+		This function will save an item to the cache store. If saving fails, the
+		function will return FALSE.
+
+		:param string $id: name of the cached item
+		:param mixed $data: the data to save
+		:param int $ttl: Time To Live, in seconds (default 60)
+		:returns: TRUE on success, FALSE on failure
+		:rtype: Boolean
+
+		::
+
+			$this->cache->save('cache_item_id', 'data_to_cache');
+	
+delete()
+========
+
+	.. php:method:: delete ( $id )
+	
+		This function will delete a specific item from the cache store. If item
+		deletion fails, the function will return FALSE.
+
+		:param string $id: name of cached item
+		:returns: TRUE if deleted, FALSE if the deletion fails
+		:rtype: Boolean
+		
+		::
+
+			$this->cache->delete('cache_item_id');
+
+clean()
+=======
+
+	.. php:method:: clean ( )
+	
+		This function will 'clean' the entire cache. If the deletion of the
+		cache files fails, the function will return FALSE.
+
+		:returns: TRUE if deleted, FALSE if the deletion fails
+		:rtype: Boolean
+		
+		::
+
+			$this->cache->clean();
+
+cache_info()
+=============
+
+	.. php:method:: cache_info ( )
+
+		This function will return information on the entire cache.
+
+		:returns: information on the entire cache
+		:rtype: Mixed
+		
+		::
+
+			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()
+===============
+
+	.. php:method:: get_metadata ( $id )
+	
+		This function will return detailed information on a specific item in the
+		cache.
+		
+		:param string $id: name of cached item
+		:returns: metadadta for the cached item
+		:rtype: Mixed
+		
+		::
+
+			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 functions 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 <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 functions 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 functions 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 <http://php.net/memcached>`_
+
+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.