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

Larry Ullman committed
4 5
Aliases are used to represent file paths or URLs so that you don't have to hard-code absolute paths or URLs in your project. An alias must start with the `@` character to be differentiated from normal file paths and URLs. Yii has many pre-defined aliases already available. 
For example, the alias `@yii` represents the installation path of the Yii framework; `@web` represents
Qiang Xue committed
6
the base URL for the currently running Web application.
Qiang Xue committed
7 8


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

Larry Ullman committed
12
You can define an alias for a file path or URL by calling [[Yii::setAlias()]]:
Qiang Xue committed
13

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

Larry Ullman committed
18
// an alias of a URL
Qiang Xue committed
19 20 21
Yii::setAlias('@bar', 'http://www.example.com');
```

Larry Ullman committed
22
> Note: The file path or URL being aliased may *not* necessarily refer to an existing file or resource.
Qiang Xue committed
23

Larry Ullman committed
24 25 26
Given a defined alias, you may derive a new alias (without the need of calling [[Yii::setAlias()]]) by appending
a slash `/` followed with one or more path segments. The aliases defined via [[Yii::setAlias()]] becomes the 
*root alias*, while aliases derived from it are *derived aliases*. For example, `@foo` is a root alias,
Qiang Xue committed
27 28
while `@foo/bar/file.php` is a derived alias.

Larry Ullman committed
29
You can define an alias using another alias (either root or derived):
Qiang Xue committed
30 31 32 33 34 35 36

```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
37
For convenience, [Application](structure-applications.md) provides a writable property named `aliases`
Larry Ullman committed
38
that you can configure in the application [configuration](concept-configurations.md):
Qiang Xue committed
39 40 41 42 43 44 45 46 47 48 49 50

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


Qiang Xue committed
51
Resolving Aliases <a name="resolving-aliases"></a>
Qiang Xue committed
52 53
-----------------

Larry Ullman committed
54 55
You can call [[Yii::getAlias()]] to resolve a root alias into the file path or URL it represents.
The same method can also resolve a derived alias into the corresponding file path or URL:
Qiang Xue committed
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70

```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
Larry Ullman committed
71
the corresponding file path or URL:
Qiang Xue committed
72 73 74 75 76 77 78 79 80 81 82

```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
83
Using Aliases <a name="using-aliases"></a>
Qiang Xue committed
84 85
-------------

Larry Ullman committed
86 87
Aliases are recognized in many places in Yii without needing to call [[Yii::getAlias()]] to convert
them into paths or URLs. For example, [[yii\caching\FileCache::cachePath]] can accept both a file path
Qiang Xue committed
88 89 90 91 92 93 94 95 96 97 98 99 100 101
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
102
Predefined Aliases <a name="predefined-aliases"></a>
Qiang Xue committed
103 104
------------------

Larry Ullman committed
105
Yii predefines a set of aliases to easily reference commonly used file paths and URLs:
Qiang Xue committed
106

Larry Ullman committed
107 108 109 110 111 112
- `@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 [[yii\base\Application::vendorPath|Composer vendor directory]]
- `@webroot`, the Web root directory of the currently running Web application
- `@web`, the base URL of the currently running Web application
Qiang Xue committed
113

Larry Ullman committed
114
The `@yii` alias is defined when you include the `Yii.php` file in your [entry script](structure-entry-scripts.md). The rest of the aliases are defined in the application constructor when applying the application
Qiang Xue committed
115
[configuration](concept-configurations.md).
Qiang Xue committed
116 117


Qiang Xue committed
118
Extension Aliases <a name="extension-aliases"></a>
Qiang Xue committed
119 120 121
-----------------

An alias is automatically defined for each [extension](structure-extensions.md) that is installed via Composer.
Larry Ullman committed
122
Each alias is named after the root namespace of the extension as declared in its `composer.json` file, and each alias
Qiang Xue committed
123
represents the root directory of the package. For example, if you install the `yiisoft/yii2-jui` extension,
Larry Ullman committed
124
you will automatically have the alias `@yii/jui` defined during the [bootstrapping](runtime-bootstrapping.md) stage, equivalent to:
Qiang Xue committed
125 126 127 128

```php
Yii::setAlias('@yii/jui', 'VendorPath/yiisoft/yii2-jui');
```