Docs: caching WIP.

12 years ago · 33c36f2a13
1 changed files with 190 additions and 0 deletions
--- a/docs/guide/caching.md
+++ b/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