guide WIP [skip ci]

docs/guide/README.md

@@ -31,7 +31,7 @@ Application Structure
 ---------------------
 
 * [Entry Scripts](structure-entry-scripts.md)
-* **TBD** [Applications](structure-applications.md)
+* [Applications](structure-applications.md)
 * [Controllers and Actions](structure-controllers.md)
 * [Views](structure-views.md)
 * [Models](structure-models.md)

docs/guide/caching-http.md

@@ -2,11 +2,35 @@ HTTP Caching
 ============
 
 Besides server-side caching that we have described in the previous sections, Web applications may
-also exploit client-side caching to skip transmitting the same page content. To enable client-side
-caching, you may use [[yii\filters\HttpCache]] which generates appropriate cache-related HTTP headers.
+also exploit client-side caching to save the time for generating and transmitting the same page content.
 
-[[yii\filters\HttpCache|HttpCache]] is an [action filter](runtime-filtering.md) that can be used
-like the following in a controller class:
+To use client-side caching, you may configure [[yii\filters\HttpCache]] as a filter for controller
+actions whose rendering result may be cached on the client side. [[yii\filters\HttpCache|HttpCache]]
+only works for `GET` and `HEAD` requests. It can handle three kinds of cache-related HTTP headers for these requests:
+
+* [[yii\filters\HttpCache::lastModified|Last-Modified]]
+* [[yii\filters\HttpCache::etagSeed|Etag]]
+* [[yii\filters\HttpCache::cacheControlHeader|Cache-Control]]
+
+
+## `Last-Modified` Header <a name="last-modified"></a>
+
+The `Last-Modified` header uses a timestamp to indicate if the page has been modified since the client caches it.
+
+You may configure the [[yii\filters\HttpCache::lastModified]] property to enable sending
+the `Last-Modified` header. The property should be a PHP callable returning a UNIX timestamp about
+the page modification time. The signature of the PHP callable should be as follows,
+
+```php
+/**
+ * @param Action $action the action object that is being handled currently
+ * @param array $params the value of the "params" property
+ * @return integer a UNIX timestamp representing the page modification time
+ */
+function ($action, $params)
+```
+
+The following is an example of making use of the `Last-Modified` header:
 
 ```php
 public function behaviors()
@@ -31,30 +55,6 @@ If the browser visits the same page again and there is no post being modified du
 the server will not re-generate the page, and the browser will use the cached version on the client side.
 As a result, server-side rendering and page content transmission are both skipped.
 
-[[yii\filters\HttpCache|HttpCache]] only works for `GET` and `HEAD` requests. It can handle
-three kinds of cache-related HTTP headers for these requests:
-
-* [[yii\filters\HttpCache::lastModified|Last-Modified]]
-* [[yii\filters\HttpCache::etagSeed|Etag]]
-* [[yii\filters\HttpCache::cacheControlHeader|Cache-Control]]
-
-
-## `Last-Modified` Header <a name="last-modified"></a>
-
-The `Last-Modified` header uses a timestamp to indicate if the page has been modified since the client caches it.
-
-You may configure the [[yii\filters\HttpCache::lastModified]] property to enable sending
-the `Last-Modified` header. The property should be a PHP callable returning a UNIX timestamp about
-the page modification time. The signature of the PHP callable should be as follows,
-
-```php
-/**
- * @param Action $action the action object that is being handled currently
- * @param array $params the value of the "params" property
- * @return integer a UNIX timestamp representing the page modification time
- */
-function ($action, $params)
-```
 
 ## `ETag` Header <a name="etag"></a>
 
@@ -75,6 +75,31 @@ should be as follows,
 function ($action, $params)
 ```
 
+The following is an example of making use of the `ETag` header:
+
+```php
+public function behaviors()
+{
+    return [
+        [
+            'class' => 'yii\filters\HttpCache',
+            'only' => ['view'],
+            'etagSeed' => function ($action, $params) {
+                $post = $this->findModel(\Yii::$app->request->get('id'));
+                return serialize([$post->title, $post->content]);
+            },
+        ],
+    ];
+}
+```
+
+The above code states that HTTP caching should be enabled for the `view` action only. It should
+generate an `ETag` HTTP header based on the title and content of the requested post. When a browser visits
+the `view` page for the first time, the page will be generated on the server and sent to the browser;
+If the browser visits the same page again and there is change to the title and content of the post,
+the server will not re-generate the page, and the browser will use the cached version on the client side.
+As a result, server-side rendering and page content transmission are both skipped.
+
 ETags allow more complex and/or more precise caching strategies than `Last-Modified` headers.
 For instance, an ETag can be invalidated if the site has switched to another theme.
 

docs/guide/structure-applications.md

+Applications
+============
+
+Applications represent execution contexts within which requests are being processed.
+The main task of applications is to analyze requests and dispatch them to appropriate
+[controllers](structure-controllers.md) for further processing. For this reason, applications
+are also called *front controllers*.
+
+There are two main types of applications: [[yii\web\Application|Web applications]] and
+[[yii\console\Application|console applications]]. As the names indicate, the former mainly handles
+Web requests while the latter console command requests.
+
+Applications are usually instantiated in [entry scripts](structure-entry-scripts.md) and can be globally accessed
+via the expression `Yii::$app`.
+
+
+## Configurations
+
+When applications are being instantiated in [entry scripts](structure-entry-scripts.md), they
+need to be configured to well describe the execution contexts. For example, the applications need
+to know where to look for controller classes, where to store temporary files, etc. These information
+are typically represented in terms of [configurations](concept-configurations.md) and stored in
+one or multiple configuration files, called application configuration files.
+
+The following code in an entry script shows how an application instance is created and configured using
+the configuration loaded from a configuration file `web.php`:
+
+```php
+require(__DIR__ . '/../vendor/autoload.php');
+require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');
+
+// load application configuration
+$config = require(__DIR__ . '/../config/web.php');
+
+// instantiate and configure the application
+(new yii\web\Application($config))->run();
+```
+
+
+
+## Application Components
+
+Applications are [service locators](concept-service-locators.md). They host a set of the so-called
+*application components* that provide different services for request processing. For example,
+the `urlManager` component is responsible for routing Web requests to appropriate controllers;
+the `db` component provides DB-related services; and so on.
+
+Each application component has an ID that uniquely identifies itself among other application components
+in the same application. You can access an application component through the expression `$app->ID`,
+where `$app` refers to an application instance, and `ID` stands for the ID of an application component.
+For example, you can use `Yii::$app->db` to get the [[yii\db\Connection|DB connection]], and `Yii::$app->cache`
+to get the [[yii\caching\Cache|primary cache]] registered with the application.
+
+Application components can be any objects. You can register them with an application to make them
+globally accessible. This is usually done by configuring the [[yii\base\Application::components]] property in the
+application configuration like the following:
+
+```php
+[
+    'components' => [
+        'cache' => [
+            'class' => 'yii\caching\FileCache',
+        ],
+        'mail' => [
+            'class' => 'yii\swiftmailer\Mailer',
+        ],
+    ],
+]
+```
+
+The array keys are the IDs of the application components, and the array values are the
+[configurations](concept-configurations.md) for the corresponding application components.
+
+
+Yii predefines a set of core application components to provide features
+common among Web applications. For example, the
+[request|CWebApplication::request] component is used to collect
+information about a user request and provide information such as the
+requested URL and cookies.  By configuring the properties of these core
+components, we can change the default behavior of nearly every aspect
+of Yii.
+
+Here is a list the core components that are pre-declared by [CWebApplication]:
+
+   - [assetManager|CWebApplication::assetManager]: [CAssetManager] -
+manages the publishing of private asset files.
+
+   - [authManager|CWebApplication::authManager]: [CAuthManager] - manages role-based access control (RBAC).
+
+   - [cache|CApplication::cache]: [CCache] - provides data caching
+functionality. Note, you must specify the actual class (e.g.
+[CMemCache], [CDbCache]). Otherwise, null will be returned when you
+access this component.
+
+   - [clientScript|CWebApplication::clientScript]: [CClientScript] -
+manages client scripts (javascript and CSS).
+
+   - [coreMessages|CApplication::coreMessages]: [CPhpMessageSource] -
+provides translated core messages used by the Yii framework.
+
+   - [db|CApplication::db]: [CDbConnection] - provides the database
+connection. Note, you must configure its
+[connectionString|CDbConnection::connectionString] property in order
+to use this component.
+
+   - [errorHandler|CApplication::errorHandler]: [CErrorHandler] - handles
+uncaught PHP errors and exceptions.
+
+   - [format|CApplication::format]: [CFormatter] - formats data values
+for display purpose.
+
+   - [messages|CApplication::messages]: [CPhpMessageSource] - provides
+translated messages used by the Yii application.
+
+   - [request|CWebApplication::request]: [CHttpRequest] - provides
+information related to user requests.
+
+   - [securityManager|CApplication::securityManager]: [CSecurityManager] -
+provides security-related services, such as hashing and encryption.
+
+   - [session|CWebApplication::session]: [CHttpSession] - provides
+session-related functionality.
+
+   - [statePersister|CApplication::statePersister]: [CStatePersister] -
+provides the mechanism for persisting global state.
+
+   - [urlManager|CWebApplication::urlManager]: [CUrlManager] - provides
+URL parsing and creation functionality.
+
+   - [user|CWebApplication::user]: [CWebUser] - carries identity-related
+information about the current user.
+
+   - [themeManager|CWebApplication::themeManager]: [CThemeManager] - manages themes.
+
+
+## Application Lifecycle
+
+
+When handling a user request, an application will undergo the following
+life cycle:
+
+   0. Pre-initialize the application with [CApplication::preinit()];
+
+   1. Set up the error handling;
+
+   2. Register core application components;
+
+   3. Load application configuration;
+
+   4. Initialize the application with [CApplication::init()]
+       - Register application behaviors;
+	   - Load static application components;
+
+   5. Raise an [onBeginRequest|CApplication::onBeginRequest] event;
+
+   6. Process the user request:
+	   - Collect information about the request;
+	   - Create a controller;
+	   - Run the controller;
+
+   7. Raise an [onEndRequest|CApplication::onEndRequest] event;
+