diff --git a/docs/guide/README.md b/docs/guide/README.md index c44da5fa8a..19ec4156ea 100644 --- a/docs/guide/README.md +++ b/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) diff --git a/docs/guide/basic-aliases.md b/docs/guide/basic-aliases.md index 1da0ce28fa..eb7ae38121 100644 --- a/docs/guide/basic-aliases.md +++ b/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 -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. +Defining Aliases +---------------- -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. -- `@app` - base path of currently running application. -- `@runtime` - runtime directory. -- `@vendor` - Composer vendor directory. -- `@webroot` - web root directory of currently running web application. -- `@web` - base URL of currently running web application. +```php +// an alias of file path +Yii::setAlias('@foo', '/path/to/foo'); +// 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'); +``` diff --git a/docs/guide/basic-autoloading.md b/docs/guide/basic-autoloading.md index c7743f4916..e10a8e486b 100644 --- a/docs/guide/basic-autoloading.md +++ b/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. diff --git a/docs/guide/basic-configs.md b/docs/guide/basic-configs.md index 8efe2951e4..2baa71b533 100644 --- a/docs/guide/basic-configs.md +++ b/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