guide WIP [skip ci]

docs/guide/README.md

@@ -41,7 +41,7 @@ Application Structure
 * [Filters](structure-filters.md)
 * [Widgets](structure-widgets.md)
 * [Asset Bundles](structure-assets.md)
-* **TBD** [Extensions](structure-extensions.md)
+* [Extensions](structure-extensions.md)
 
 
 Handling Requests

docs/guide/start-forms.md

@@ -47,7 +47,8 @@ class EntryForm extends Model
 The class extends from [[yii\base\Model]], a base class provided by Yii, commonly used to
 represent form data.
 
-> Info: [[yii\base\Model]] is used as a parent for model classes *not* associated with database tables. [[yii\db\ActiveRecord]] is normally the parent for model classes that do correspond to database tables.
+> Info: [[yii\base\Model]] is used as a parent for model classes *not* associated with database tables.
+[[yii\db\ActiveRecord]] is normally the parent for model classes that do correspond to database tables.
 
 The `EntryForm` class contains two public members, `name` and `email`, which are used to store
 the data entered by the user. It also contains a method named `rules()`, which returns a set
@@ -117,18 +118,19 @@ with the data from `$_POST`, provided in Yii by [[yii\web\Request::post()]].
 If the model is successfully populated (i.e., if the user has submitted the HTML form), the action will call
 [[yii\base\Model::validate()|validate()]] to make sure the values entered are valid.
 
-If everything is fine, the action will render a view named `entry-confirm` to confirm the data entered 
-with the user that the data entered. If no data was submitted or the data contained errors, the `entry` view will
-be rendered, wherein the HTML form  will be shown, along with any validation error messages.
-
 > Info: The expression `Yii::$app` represents the [application](structure-applications.md) instance,
   which is a globally accessible singleton. It is also a [service locator](concept-service-locator.md) that
   provides components such as `request`, `response`, `db`, etc. to support specific functionality.
   In the above code, the `request` component of the application instance is used to access the `$_POST` data.
 
-> Note: In this very simple example we just render the confirmation page, however when you process POST data you
-  should better use [[yii\web\Controller::refresh()|refresh()]] or [[yii\web\Controller::redirect()|redirect()]]
-  to avoid [resubmitting](http://en.wikipedia.org/wiki/Post/Redirect/Get) forms.
+If everything is fine, the action will render a view named `entry-confirm` to confirm the data entered 
+with the user that the data entered. If no data is submitted or the data contains errors, the `entry` view will
+be rendered, wherein the HTML form will be shown, along with any validation error messages.
+
+> Note: In this very simple example we just render the confirmation page upon valid data submission. In practice,
+  you should consider using [[yii\web\Controller::refresh()|refresh()]] or [[yii\web\Controller::redirect()|redirect()]]
+  to avoid [form resubmission problems](http://en.wikipedia.org/wiki/Post/Redirect/Get).
+
 
 Creating Views <a name="creating-views"></a>
 --------------

docs/guide/structure-extensions.md

+Extensions
+==========
+
+> Note: This section is under development.
+
+Extensions are redistributable software packages that extend Yii by providing extra features. For example,
+the [yii2-debug](tool-debugger.md) extension adds a handy debug toolbar to every page in your application
+to help you more easily grasp how the pages are generated. You can install and use extensions in your
+applications to accelerate your development process. You can also package your code in terms of extensions
+to share with other people your great work.
+
+
+## Getting Extensions
+
+The easiest way of getting extensions is using [Composer](https://getcomposer.org/). The name "extension"
+is also known as "package" in Composer's terminology. To do so, you will need to
+
+1. install [Composer](https://getcomposer.org/), which you probably have already done when
+   [installing Yii](start-installation.md).
+2. [specify which repositories](https://getcomposer.org/doc/05-repositories.md#repository) you would like
+   to get extensions from. In most cases you can skip this if you only want to install open source extensions
+   hosted on [Packagist](https://packagist.org/) - the default and biggest Composer repository.
+3. modify the `composer.json` file of your application and specify which extensions you want to use.
+4. run `php composer.phar install` to install the specified extensions.
+
+You usually only need to do Step 1 and 2 once. You may need to do Step 3 and 4 multiple times depending on your
+evolving requirements for extensions.
+
+By default, extensions installed by Composer are stored under the `BasePath/vendor` directory, where `BasePath`
+refers to the application's [base path](structure-applications.md#basePath).
+
+For example, to get the `yii2-imagine` extension maintained officially by Yii, modify your `composer.json` like the following:
+
+```json
+{
+    // ...
+
+    "require": {
+        // ... other dependencies
+
+        "yiisoft/yii2-imagine": "*"
+    }
+}
+```
+
+The installed extension will be located in the `vendor/yiisoft/yii2-imagine` directory.
+
+> Info: All extensions officially maintained by Yii are named as `yiisoft/yii2-xyz`, where `xyz` varies for different
+  extensions.
+
+
+## Using Extensions
+
+In order for your applications to use extensions, you will need to install Composer's class autoloader. This is
+necessary such that PHP classes in extensions can be properly autoloaded when you reference them in the application code.
+To do so, use the following lines in the [entry script](concept-entry-scripts.md) of your application:
+
+```php
+// install Composer's class autoloader
+require(__DIR__ . '/../vendor/autoload.php');
+
+// include Yii class file
+require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');
+```
+
+> Info: If you are using the [basic application template](start-installation.md) or
+[advanced application template](tutorial-advanced-app.md), you do not need to do anything because the application templates
+already contain the above code.
+
+Now you can enjoy using the installed extensions. For example, to use the `yii2-imagine` extension shown in the last
+subsection, you can write code like the following in your application, where `Image` is the class provided by
+the extension:
+
+```php
+use Yii;
+use yii\imagine\Image;
+
+// generate a thumbnail image
+Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
+    ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);
+```
+
+
+## Creating Extensions
+
+## Core Extensions
+

extensions/imagine/Image.php

@@ -13,11 +13,9 @@ namespace yii\imagine;
  * Example of use:
  *
  * ~~~php
- * // thumb - saved on runtime path
- * $imagePath = Yii::$app->getBasePath() . '/web/img/test-image.jpg';
- * $runtimePath = Yii::$app->getRuntimePath();
- * Image::thumbnail('@app/web/img/test-image.jpg', 120, 120)
- *     ->save('thumb-test-image.jpg', ['quality' => 50]);
+ * // generate a thumbnail image
+ * Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
+ *     ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);
  * ~~~
  *
  * @author Antonio Ramirez <amigo.cobos@gmail.com>