guide WIP [skip ci]

docs/guide/extend-creating-extensions.md

@@ -3,7 +3,7 @@ Extending Yii
 
 > Note: This section is under development.
 
-The Yii framework was designed to be easily extendable. Additional features can be added to your project and then reused, either by yourself on other projects or by sharing your work as a formal Yii extension.
+The Yii framework was designed to be easily extensible. Additional features can be added to your project and then reused, either by yourself on other projects or by sharing your work as a formal Yii extension.
 
 Code style
 ----------

docs/guide/extend-customizing-core.md

-Helper Classes
-==============
-
-> Note: This section is under development.
-
-Yii provides many classes that help simplify  common coding tasks, such as string or array manipulations,
-HTML code generation, and so forth. These helper classes are organized under the `yii\helpers` namespace and
-are all static classes (meaning they contain only static properties and methods and should not be instantiated).
-
-
-You use a helper class by directly calling one of its static methods:
-
-
-```
-use yii\helpers\ArrayHelper;
-
-$c = ArrayHelper::merge($a, $b);
-```
-
-Extending Helper Classes
-------------------------
-
-To make helper classes easier to extend, Yii breaks each helper class into two classes: a base class (e.g. `BaseArrayHelper`)
-and a concrete class (e.g. `ArrayHelper`). When you use a helper, you should only use the concrete version, never use the base class.
-
-If you want to customize a helper, perform the following steps (using `ArrayHelper` as an example):
-
-1. Name your class the same as the concrete class provided by Yii, including the namespace: `yii\helpers\ArrayHelper`
-2. Extend your class from the base class: `class ArrayHelper extends \yii\helpers\BaseArrayHelper`.
-3. In your class, override any method or property as needed, or add new methods or properties.
-4. Tell your application to use your version of the helper class by including the following line of code in the bootstrap script:
-
-```php
-Yii::$classMap['yii\helpers\ArrayHelper'] = 'path/to/ArrayHelper.php';
-```
-
-Step 4 above will instruct the Yii class autoloader to load your version of the helper class instead of the one included in the Yii distribution.
-
-> Tip: You can use `Yii::$classMap` to replace ANY core Yii class with your own customized version, not just helper classes.

docs/guide/extend-using-composer.md

@@ -22,6 +22,20 @@ curl -s http://getcomposer.org/installer | php
 
 We strongly recommend a global composer installation.
 
+Installing Composer Class Autoloader
+------------------------------------
+
+Make sure the [entry script](concept-entry-scripts.md) of your application contains the following lines of code:
+
+```php
+// install Composer's class autoloader
+require(__DIR__ . '/../vendor/autoload.php');
+
+// include Yii class file
+require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');
+```
+
+
 Working with composer
 ---------------------
 
@@ -52,7 +66,7 @@ composer.phar update
 
 As an example, packages on `dev-master` will constantly get new updates when you run `update`, while running `install` won't, unless you've pulled an update of the `composer.lock` file.
 
-There are several paramaters available to the above commands. Very commonly used ones are `--no-dev`, which would skip packages in the `require-dev` section and `--prefer-dist`, which downloads archives if available, instead of checking out repositories to your `vendor` folder.
+There are several parameters available to the above commands. Very commonly used ones are `--no-dev`, which would skip packages in the `require-dev` section and `--prefer-dist`, which downloads archives if available, instead of checking out repositories to your `vendor` folder.
 
 > Composer commands must be executed within your Yii project's directory, where the `composer.json` file can be found.
 Depending upon your operating system and setup, you may need to provide paths to the PHP executable and
@@ -100,7 +114,7 @@ afterwards.
 > Depending on the package additional configuration may be required (eg. you have to register a module in the config), but autoloading of the classes should be handled by composer.
 
 
-Using a specifc version of a package
+Using a specific version of a package
 ------------------------------------
 
 Yii always comes with the latest version of a required library that it is compatible with, but allows you to use an older version if you need to.

docs/guide/helper-overview.md

@@ -3,14 +3,26 @@ Helpers
 
 > Note: This section is under development.
 
-Helper classes typically contain static methods only and are used as follows:
+Yii provides many classes that help simplify common coding tasks, such as string or array manipulations,
+HTML code generation, and so on. These helper classes are organized under the `yii\helpers` namespace and
+are all static classes (meaning they contain only static properties and methods and should not be instantiated).
+
+You use a helper class by directly calling one of its static methods, like the following:
 
 ```php
-use \yii\helpers\Html;
+use yii\helpers\Html;
+
 echo Html::encode('Test > test');
 ```
 
-There are several classes provided by framework:
+> Note: To support [extending helper classes](#extending-helper-classes), Yii breaks each core helper class
+  into two classes: a base class (e.g. `BaseArrayHelper`) and a concrete class (e.g. `ArrayHelper`).
+  When you use a helper, you should only use the concrete version and never use the base class.
+
+
+## Core Helper Classes
+
+The following core helper classes are provided in the Yii releases:
 
 - ArrayHelper
 - Console
@@ -25,3 +37,39 @@ There are several classes provided by framework:
 - StringHelper
 - Url
 - VarDumper
+
+
+## Extending Helper Classes
+
+To custom a core helper class (e.g. `yii\helpers\ArrayHelper`), you should extend from its corresponding base class
+(e.g. `yii\helpers\BaseArrayHelper`) and name your class the same as the corresponding concrete class
+(e.g. `yii\helpers\ArrayHelper`), including its namespace.
+
+The following example shows how to customize the [[yii\helpers\ArrayHelper::merge()|merge()]] method of the
+[[yii\helpers\ArrayHelper]] class:
+
+```php
+namespace yii\helpers;
+
+use yii\helpers\BaseArrayHelper;
+
+class ArrayHelper extends BaseArrayHelper
+{
+    public static function merge($a, $b)
+    {
+        // your custom implementation
+    }
+}
+```
+
+Save your class in a file named `ArrayHelper.php`. The file can be in any directory, such as `@app/components`.
+
+Next, in your application's [entry script](structure-entry-scripts.md), add the following line of code
+after including the `yii.php` file:
+
+```php
+Yii::$classMap['yii\helpers\ArrayHelper'] = 'path/to/ArrayHelper.php';
+```
+
+The above line instructs the [Yii class autoloader](concept-autoloading.md) to load your version of the helper
+class, instead of the one included in the Yii releases.

docs/guide/structure-extensions.md

@@ -3,33 +3,36 @@ 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.
+Extensions are redistributable software packages specifically designed to be used in Yii applications and provide
+ready-to-use features. For example, the [yiisoft/yii2-debug](tool-debugger.md) extension adds a handy debug toolbar
+at the bottom of every page in your application to help you more easily grasp how the pages are generated. You can
+use extensions to accelerate your development process. You can also package your code as extensions to share with
+other people your great work.
 
+> Info: We use the term "extension" to refer to Yii-specific software packages. For general purpose software packages
+  that can be used without Yii, we will refer to them using the term "package".
 
-## 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
+## Using Extensions
+
+To use an extension, you need to install it first. Most extensions are distributed as [Composer](https://getcomposer.org/)
+packages, and you can take the following two simple steps to install such an extension:
+
+1. modify the `composer.json` file of your application and specify which extensions (Composer packages) you want to install.
+2. run `php composer.phar install` to install the specified extensions.
 
-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 may need to install [Composer](https://getcomposer.org/) if you do not have it. Composer is a dependency
+manager. This means when installing a package, it will install all its dependent packages automatically.
 
-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.
+> Info: By default, Composer installs packages registered on [Packagist](https://packagist.org/) - the biggest repository
+  for open source Composer packages. You may also [create your own repository](https://getcomposer.org/doc/05-repositories.md#repository)
+  and configure Composer to use it. This is useful if you are developing closed open extensions and want to share
+  within your projects.
 
-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).
+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:
+For example, to install the `yiisoft/yii2-imagine` extension, modify your `composer.json` like the following:
 
 ```json
 {
@@ -43,33 +46,15 @@ For example, to get the `yii2-imagine` extension maintained officially by Yii, m
 }
 ```
 
-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');
-```
+After the installation, you should see the directory `yiisoft/yii2-imagine` under `BasePath/vendor`. You should
+also see another directory `imagine/imagine` which contains the installed dependent package.
 
-> 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.
+> Info: The `yiisoft/yii2-imagine` is a core extension developed and maintained by the Yii developer team. All
+  core extensions are hosted on [Packagist](https://packagist.org/) and named like `yiisoft/yii2-xyz`, where `xyz`
+  varies for different extensions.
 
-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:
+Now you can use the installed extensions like they are part of your application. The following example shows
+how you can use the `yii\imagine\Image` class provided by the `yiisoft/yii2-imagine` extension:
 
 ```php
 use Yii;
@@ -80,8 +65,98 @@ Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
     ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);
 ```
 
+> Info: Extension classes are autoloaded using the [Yii class autoloader](concept-autoloading.md). Yii automatically
+  creates [aliases](concept-aliases.md#extension-aliases) for the root namespaces declared by the extensions.
+
+Also make sure in the [application configuration](structure-applications.md#application-configurations), you have
+configured `extension
+
 
 ## Creating Extensions
 
+You may consider creating an extension when you feel the need to redistribute some of your great code so that
+they can be easily reused by other people or in your other projects.
+
+An extension can contain any code you like, such as a helper class, a widget, a module, etc.
+
+It is recommended that you create an extension in terms of a Composer package so that it can be more easily
+used elsewhere, liked described in the last subsection. Below are the steps you may follow to create an extension.
+
+1. Put all the files you plan to include in the extension in a single directory. The directory should contain
+   no other irrelevant files. For simplicity, let's call this directory the extension's *root directory*.
+2. Create a `composer.json` file directly under the root directory. The file is required by Composer, which describes
+   the metadata about your extension. Please refer to the [Composer Manual](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup)
+   for more details about the file format.
+3. Create a VCS (version control system) repository to host the extension files. Any future development
+   and maintenance work about the extension should be done on this repository.
+4. Register your extension with a Composer repository so that other users can find and install your extension.
+   If you are creating an open source extension, you can register it with [Packagist](https://packagist.org/);
+   If you are creating a private extension for internal use, you may register it with
+   [your own repository](https://getcomposer.org/doc/05-repositories.md#hosting-your-own).
+
+As an example, you may refer to the [yiisoft/yii2-bootstrap](widget-bootstrap) extension which provides a set of
+widgets encapsulating the Twitter Bootstrap plugins. The extension is hosted on [GitHub](https://github.com/yiisoft/yii2-bootstrap)
+and registered with [Packagist](https://packagist.org/packages/yiisoft/yii2-bootstrap). Below is the content
+of its `composer.json` file (some unimportant content is removed for simplicity):
+
+```json
+{
+    "name": "yiisoft/yii2-bootstrap",
+    "description": "The Twitter Bootstrap extension for the Yii framework",
+    "keywords": ["yii2", "bootstrap"],
+    "type": "yii2-extension",
+    "license": "BSD-3-Clause",
+    "require": {
+        "yiisoft/yii2": "*",
+        "twbs/bootstrap": "3.1.* | 3.0.*"
+    },
+    "autoload": {
+        "psr-4": {
+            "yii\\bootstrap\\": ""
+        }
+    }
+}
+```
+
+
+### Yii2 Extensions
+
+When creating a Composer package, you may specify the package type to be `yii2-extension`, like shown in the example
+in the last subsection. This is recommended if your package is an extension that is specifically designed to be
+used in Yii applications. By using `yii2-extension` as the package type, your package can get the following extra benefits:
+
+
+For example, if your package contains a Yii [widget](structure-widgets.md), it is most likely
+that the package
+
+
+## Installing Extensions Manually
+
+In some rare occasions, you may want to install some or all extensions manually, rather than relying on Composer.
+To do so, you should
+
+1. download the extension archive files and unpack them in the `vendor` directory.
+2. install the class autoloaders provided by the extensions, if any.
+3. download and install all dependent extensions as instructed.
+
+If an extension does not have a class autoloader but follows the
+[PSR-4 standard](https://github.com/php-fig/fig-standards/blob/master/proposed/psr-4-autoloader/psr-4-autoloader.md),
+you may use the class autoloader provided by Yii to autoload the extension classes. All you need to do is just to
+declare a [root alias](concept-aliases.md#defining-aliases) for the extension root directory. For example,
+assuming you have installed an extension in the directory `vendor/mycompany/myext`, and the extension classes
+are under the `myext` namespace, then you can include the following code in your application configuration:
+
+```php
+[
+    'aliases' => [
+        '@myext' => '@vendor/mycompany/myext',
+    ],
+]
+```
+
+
 ## Core Extensions
 
+
+## Best Practices
+