Finished alias guide.

docs/guide/README.md

@@ -35,6 +35,7 @@ Application Structure
 * [Models](structure-models.md)
 * **TBD** [Widgets](structure-widgets.md)
 * **TBD** [Modules](structure-modules.md)
+* **TBD** [Extensions](structure-extensions.md)
 
 
 Handling Requests
@@ -49,17 +50,16 @@ Handling Requests
 * **TBD** [Filtering](runtime-filtering.md)
 
 
-Basic Concepts
+Key Concepts
---------------
+------------
 
 * [Components](basic-components.md)
 * [Properties](basic-properties.md)
 * [Events](basic-events.md)
 * [Behaviors](basic-behaviors.md)
 * [Configurations](basic-configs.md)
-* [Class Autoloading](basic-autoloading.md)
 * [Aliases](basic-alias.md)
-* **TBD** [Extensions](basic-extensions.md)
+* [Class Autoloading](basic-autoloading.md)
 * [Service Locator](basic-service-locator.md)
 * [Dependency Injection Container](basic-di-container.md)
 
@@ -77,8 +77,8 @@ Working with Databases
 * **TBD** [ElasticSearch](db-elastic-search.md)
 
 
-Collecting Inputs
+Getting User Inputs
------------------
+-------------------
 
 * [Creating Forms](input-forms.md)
 * [Input Validation](input-validation.md)

docs/guide/basic-aliases.md

@@ -1,25 +1,131 @@
-Path Aliases
+Aliases
-============
+=======
 
-> Note: This chapter is under development.
+Aliases are used to represent file paths or URLs to avoid hard-coding absolute paths or URLs in your code.
+An alias must start with a `@` character so that it can be differentiated from file paths and URLs.
+For example, the alias `@yii` represents the installation path of the Yii framework, while `@web` represents
+the base URL for the currently running Web application.
 
-Yii 2.0 expands the usage of path aliases to both file/directory paths and URLs. An alias
-must start with an `@` symbol so that it can be differentiated from file/directory paths and URLs.
-For example, the alias `@yii` refers to the Yii installation directory while `@web` contains the base URL for the currently running web application. Path aliases are supported in most places in the Yii core code. For example, `FileCache::cachePath` can accept both a path alias and a normal directory path.
 
-Path aliases are also closely related to class namespaces. It is recommended that a path
+Defining Aliases
-alias should be defined for each root namespace so that Yii's class autoloader can be used without
+----------------
-any further configuration. For example, because `@yii` refers to the Yii installation directory,
-a class like `yii\web\Request` can be autoloaded by Yii. If you use a third party library
-such as Zend Framework, you may define a path alias `@Zend` which refers to its installation
-directory and Yii will be able to autoload any class in this library.
 
-The following aliases are predefined by the core framework:
+You can call [[Yii::setAlias()]] to define an alias for a given file path or URL. For example,
 
-- `@yii` - framework directory.
+```php
-- `@app` - base path of currently running application.
+// an alias of file path
-- `@runtime` - runtime directory.
+Yii::setAlias('@foo', '/path/to/foo');
-- `@vendor` - Composer vendor directory.
-- `@webroot` - web root directory of currently running web application.
-- `@web` - base URL of currently running web application.
 
+// an alias of URL
+Yii::setAlias('@bar', 'http://www.example.com');
+```
+
+> Note: A file path or URL being aliased may NOT necessarily refer to an existing file or resource.
+
+Given an alias, you may derive a new alias (without the need of calling [[Yii::setAlias()]]) by appending
+a slash `/` followed with one or several path segments. We call the aliases defined via [[Yii::setAlias()]]
+*root aliases*, while the aliases derived from them *derived aliases*. For example, `@foo` is a root alias,
+while `@foo/bar/file.php` is a derived alias.
+
+You can define an alias using another alias (either root alias or derived alias is fine):
+
+```php
+Yii::setAlias('@foobar', '@foo/bar');
+```
+
+Root aliases are usually defined during the [bootstrapping](runtime-bootstrapping.md) stage.
+For example, you may call [[Yii::setAlias()]] in the [entry script](structure-entry-scripts.md).
+For convenience, [Application](structure-applications.md) provides writable property named `aliases`
+that you can configure in the application [configuration](basic-configs.md), like the following,
+
+```php
+return [
+    // ...
+    'aliases' => [
+        '@foo' => '/path/to/foo',
+        '@bar' => 'http://www.example.com',
+    ],
+];
+```
+
+
+Resolving Aliases
+-----------------
+
+You can call [[Yii::getAlias()]] to resolve a root alias into the file path or URL it is representing.
+The same method can also resolve a derived alias into the corresponding file path or URL. For example,
+
+```php
+echo Yii::getAlias('@foo');               // displays: /path/to/foo
+echo Yii::getAlias('@bar');               // displays: http://www.example.com
+echo Yii::getAlias('@foo/bar/file.php');  // displays: /path/to/foo/bar/file.php
+```
+
+The path/URL represented by a derived alias is determined by replacing the root alias part with its corresponding
+path/URL in the derived alias.
+
+> Note: The [[Yii::getAlias()]] method does not check whether the resulting path/URL refers to an existing file or resource.
+
+
+A root alias may also contain slash `/` characters. The [[Yii::getAlias()]] method
+is intelligent enough to tell which part of an alias is a root alias and thus correctly determines
+the corresponding file path or URL. For example,
+
+```php
+Yii::setAlias('@foo', '/path/to/foo');
+Yii::setAlias('@foo/bar', '/path2/bar');
+Yii::getAlias('@foo/test/file.php');  // displays: /path/to/foo/test/file.php
+Yii::getAlias('@foo/bar/file.php');   // displays: /path2/bar/file.php
+```
+
+If `@foo/bar` is not defined as a root alias, the last statement would display `/path/to/foo/bar/file.php`.
+
+
+Using Aliases
+-------------
+
+Aliases are recognized in many places in Yii without the need of calling [[Yii::getAlias()]] to convert
+them into paths/URLs. For example, [[yii\caching\FileCache::cachePath]] can accept both a file path
+and an alias representing a file path, thanks to the `@` prefix which allows it to differentiate a file path
+from an alias.
+
+```php
+use yii\caching\FileCache;
+
+$cache = new FileCache([
+    'cachePath' => '@runtime/cache',
+]);
+```
+
+Please pay attention to the API documentation to see if a property or method parameter supports aliases.
+
+
+Predefined Aliases
+------------------
+
+Yii predefines a set of aliases to ease the need of referencing commonly used file paths and URLs.
+The following is the list of the predefined aliases:
+
+- `@yii`: the directory where the `BaseYii.php` file is located (also called the framework directory).
+- `@app`: the [[yii\base\Application::basePath|base path]] of the currently running application.
+- `@runtime`: the [[yii\base\Application::runtimePath|runtime path]] of the currently running application.
+- `@vendor`: the Composer vendor directory.
+- `@webroot`: the Web root directory of the currently running Web application.
+- `@web`: the base URL of the currently running Web application.
+
+The `@yii` alias is defined when you include the `Yii.php` file in your [entry script](structure-entry-scripts.md),
+while the rest of the aliases are defined in the application constructor when applying the application
+[configuration](basic-configs.md).
+
+
+Extension Aliases
+-----------------
+
+An alias is automatically defined for each [extension](structure-extensions.md) that is installed via Composer.
+The alias is named after the root namespace of the extension as declared in its `composer.json` file, and it
+represents the root directory of the package. For example, if you install the `yiisoft/yii2-jui` extension,
+you will automatically have the alias `@yii/jui` defined during the [bootstrapping](runtime-bootstrapping.md) stage:
+
+```php
+Yii::setAlias('@yii/jui', 'VendorPath/yiisoft/yii2-jui');
+```

docs/guide/basic-autoloading.md

@@ -1,8 +1,24 @@
-Autoloading
+Class Autoloading
-===========
+=================
 
 > Note: This chapter is under development.
 
+Yii relies on the [class autoloading mechanism](http://www.php.net/manual/en/language.oop5.autoload.php)
+to locate and include required class files. A class file will be automatically included by a class autoloader
+when the corresponding class is referenced for the first time during the code execution. Because only
+the necessary files are included and parsed, it improves the application performance.
+
+Yii comes with a high-performance class autoloader which is installed when you include the `framework/Yii.php` file
+in your [entry script](structure-entry-scripts.md). The autoloader is compliant to the
+[PSR-4 standard](https://github.com/php-fig/fig-standards/blob/master/proposed/psr-4-autoloader/psr-4-autoloader.md).
+
+Below is a list of the rules that you should follow if you want to use the Yii class autoloader to autoload
+your class files.
+
+*
+It has the benefit that a class file is included onl
+
+
 All classes, interfaces and traits are loaded automatically at the moment they are used.
 There's no need to use `include` or `require`. It is true for Composer-loaded packages as well as Yii extensions.
 

docs/guide/basic-configs.md

@@ -244,7 +244,7 @@ Environment Constants
 Configurations often vary according to the environment in which an application runs. For example,
 in development environment, you may want to use a database named `mydb_dev`, while on production server
 you may want to use the `mydb_prod` database. To facilitate switching environments, Yii provides a constant
-named `YII_ENV` that you may define in the [entry script](structure-entry.md) of your application.
+named `YII_ENV` that you may define in the [entry script](structure-entry-scripts.md) of your application.
 For example,
 
 ```php