concept-aliases.md 5.3 KB
Newer Older
Qiang Xue committed
1 2
Aliases
=======
Qiang Xue committed
3

Qiang Xue committed
4 5 6 7
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.
Qiang Xue committed
8 9


Qiang Xue committed
10
Defining Aliases <a name="defining-aliases"></a>
Qiang Xue committed
11
----------------
Qiang Xue committed
12

Qiang Xue committed
13
You can call [[Yii::setAlias()]] to define an alias for a given file path or URL. For example,
Qiang Xue committed
14

Qiang Xue committed
15 16 17
```php
// an alias of file path
Yii::setAlias('@foo', '/path/to/foo');
Qiang Xue committed
18

Qiang Xue committed
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
// 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).
Qiang Xue committed
38 39
For convenience, [Application](structure-applications.md) provides a writable property named `aliases`
that you can configure in the application [configuration](concept-configurations.md), like the following,
Qiang Xue committed
40 41 42 43 44 45 46 47 48 49 50 51

```php
return [
    // ...
    'aliases' => [
        '@foo' => '/path/to/foo',
        '@bar' => 'http://www.example.com',
    ],
];
```


Qiang Xue committed
52
Resolving Aliases <a name="resolving-aliases"></a>
Qiang Xue committed
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
-----------------

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`.


Qiang Xue committed
84
Using Aliases <a name="using-aliases"></a>
Qiang Xue committed
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
-------------

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.


Qiang Xue committed
103
Predefined Aliases <a name="predefined-aliases"></a>
Qiang Xue committed
104 105 106 107 108 109 110 111
------------------

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.
112
- `@vendor`: the [[yii\base\Application::vendorPath|Composer vendor directory].
Qiang Xue committed
113 114 115 116 117
- `@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
Qiang Xue committed
118
[configuration](concept-configurations.md).
Qiang Xue committed
119 120


Qiang Xue committed
121
Extension Aliases <a name="extension-aliases"></a>
Qiang Xue committed
122 123 124 125 126 127 128 129 130 131
-----------------

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');
```