Docs: caching WIP.

docs/guide/caching.md

@@ -1,3 +1,193 @@
 Caching
 =======
 
+Overview and Base Concepts
+--------------------------
+
+Caching is a cheap and effective way to improve the performance of a web application. By storing relatively
+static data in cache and serving it from cache when requested, we save the time needed to generate the data.
+
+Using cache in Yii mainly involves configuring and accessing a cache application component. The following
+application configuration specifies a cache component that uses [memcached](http://memcached.org/) with
+two cache servers.
+
+```php
+'components' => array(
+	'cache' => array(
+		'class' => '\yii\caching\MemCache',
+		'servers' => array(
+			array(
+				'host' => 'server1',
+				'port' => 11211,
+				'weight' => 100,
+			),
+			array(
+				'host' => 'server2',
+				'port' => 11211,
+				'weight' => 50,
+			),
+		),
+	),
+),
+```
+
+When the application is running, the cache component can be accessed through `Yii::$app->cache` call.
+
+Yii provides various cache components that can store cached data in different media. For example,
+the [[\yii\caching\MemCache]] component encapsulates the PHP [memcache](http://php.net/manual/en/book.memcache.php)
+and [memcached](http://php.net/manual/en/book.memcached.php) extensions and uses memory as the medium
+of cache storage; the [[\yii\caching\ApcCache]] component encapsulates the PHP
+[APC](http://php.net/manual/en/book.apc.php) extension; and the [[\yii\caching\DbCache]] component stores
+cached data in database table.
+
+The following is a summary of the available cache components:
+
+* [[\yii\caching\ApcCache]]: uses PHP [APC](http://php.net/manual/en/book.apc.php) extension. This option can be
+  considered as the fastest one when dealing with cache for a centralized thick application (e.g. one
+  server, no dedicated load balancers, etc.).
+
+* [[\yii\caching\DbCache]]: uses a database table to store cached data. By default, it will create and use a
+  [SQLite3](http://sqlite.org/) database under the runtime directory. You can explicitly specify a database for
+  it to use by setting its `db` property.
+
+* [[\yii\caching\DummyCache]]: presents dummy cache that does no caching at all. The purpose of this component
+  is to simplify the code that needs to check the availability of cache. For example, during development or if
+  the server doesn't have actual cache support, we can use this cache component. When an actual cache support
+  is enabled, we can switch to use the corresponding cache component. In both cases, we can use the same
+  code `Yii::$app->cache->get($key)` to attempt retrieving a piece of data without worrying that
+  `Yii::$all->cache` might be `null`.
+
+* [[\yii\caching\FileCache]]: uses standard files to store cached data. This is particular suitable
+  to cache large chunk of data (such as pages).
+
+* [[\yii\caching\MemCache]]: uses PHP [memcache](http://php.net/manual/en/book.memcache.php)
+  and [memcached](http://php.net/manual/en/book.memcached.php) extensions. This option can be considered as
+  the fastest one when dealing with cache in a distributed applications (e.g. with several servers, load
+  balancers, etc.)
+
+* [[\yii\caching\RedisCache]]: implements a cache component based on [Redis](http://redis.io/) NoSQL database.
+
+* [[\yii\caching\WinCache]]: uses PHP [WinCache](http://iis.net/downloads/microsoft/wincache-extension)
+  ([see also](http://php.net/manual/en/book.wincache.php)) extension.
+
+* [[\yii\caching\XCache]]: uses PHP [XCache](http://xcache.lighttpd.net/) extension.
+
+* [[\yii\caching\ZendDataCache]]: uses
+  [Zend Data Cache](http://files.zend.com/help/Zend-Server-6/zend-server.htm#data_cache_component.htm)
+  as the underlying caching medium.
+
+Tip: because all these cache components extend from the same base class [[Cache]], one can switch to use
+a different type of cache without modifying the code that uses cache.
+
+Caching can be used at different levels. At the lowest level, we use cache to store a single piece of data,
+such as a variable, and we call this data caching. At the next level, we store in cache a page fragment which
+is generated by a portion of a view script. And at the highest level, we store a whole page in cache and serve
+it from cache as needed.
+
+In the next few subsections, we elaborate how to use cache at these levels.
+
+Note, by definition, cache is a volatile storage medium. It does not ensure the existence of the cached
+data even if it does not expire. Therefore, do not use cache as a persistent storage (e.g. do not use cache
+to store session data or other valuable information).
+
+Data Caching
+------------
+
+Data caching is about storing some PHP variable in cache and retrieving it later from cache. For this purpose,
+the cache component base class [[\yii\caching\Cache]] provides two methods that are used most of the time:
+[[set()]] and [[get()]]. Note, only serializable variables and objects could be cached successfully.
+
+To store a variable `$value` in cache, we choose a unique `$key` and call [[set()]] to store it:
+
+```php
+Yii::$app->cache->set($key, $value);
+```
+
+The cached data will remain in the cache forever unless it is removed because of some caching policy
+(e.g. caching space is full and the oldest data are removed). To change this behavior, we can also supply
+an expiration parameter when calling [[set()]] so that the data will be removed from the cache after
+a certain period of time:
+
+```php
+// keep the value in cache for at most 45 seconds
+Yii::$app->cache->set($key, $value, 45);
+```
+
+Later when we need to access this variable (in either the same or a different web request), we call [[get()]]
+with the key to retrieve it from cache. If the value returned is `false`, it means the value is not available
+in cache and we should regenerate it:
+
+```php
+public function getCachedData()
+{
+	$key = /* generate unique key here */;
+	$value = Yii::$app->getCache()->get($key);
+	if ($value === false) {
+		$value = /* regenerate value because it is not found in cache and then save it in cache for later use */;
+		Yii::$app->cache->set($id, $value);
+	}
+	return $value;
+}
+```
+
+This is the common pattern of arbitrary data caching for general use.
+
+When choosing the key for a variable to be cached, make sure the key is unique among all other variables that
+may be cached in the application. It is **NOT** required that the key is unique across applications because
+the cache component is intelligent enough to differentiate keys for different applications.
+
+Some cache storages, such as MemCache, APC, support retrieving multiple cached values in a batch mode,
+which may reduce the overhead involved in retrieving cached data. A method named [[mget()]] is provided
+to exploit this feature. In case the underlying cache storage does not support this feature,
+[[mget()]] will still simulate it.
+
+To remove a cached value from cache, call [[delete()]]; and to remove everything from cache, call [[flush()]].
+Be very careful when calling [[flush()]] because it also removes cached data that are from other applications.
+
+Note, because CCache implements ArrayAccess, a cache component can be used liked an array. The followings
+are some examples:
+
+```php
+$cache = Yii::$app->getComponent('cache');
+$cache['var1'] = $value1;  // equivalent to: $cache->set('var1', $value1);
+$value2 = $cache['var2'];  // equivalent to: $value2 = $cache->get('var2');
+```
+
+### Cache Dependency
+
+TBD: http://www.yiiframework.com/doc/guide/1.1/en/caching.data#cache-dependency
+
+### Query Caching
+
+TBD: http://www.yiiframework.com/doc/guide/1.1/en/caching.data#query-caching
+
+Fragment Caching
+----------------
+
+TBD: http://www.yiiframework.com/doc/guide/1.1/en/caching.fragment
+
+### Caching Options
+
+TBD: http://www.yiiframework.com/doc/guide/1.1/en/caching.fragment#caching-options
+
+### Nested Caching
+
+TBD: http://www.yiiframework.com/doc/guide/1.1/en/caching.fragment#nested-caching
+
+Dynamic Content
+---------------
+
+TBD: http://www.yiiframework.com/doc/guide/1.1/en/caching.dynamic
+
+Page Caching
+------------
+
+TBD: http://www.yiiframework.com/doc/guide/1.1/en/caching.page
+
+### Output Caching
+
+TBD: http://www.yiiframework.com/doc/guide/1.1/en/caching.page#output-caching
+
+### HTTP Caching
+
+TBD: http://www.yiiframework.com/doc/guide/1.1/en/caching.page#http-caching