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. Alias defined
@ will be prefixed with
Yii has many pre-defined aliases already available. For example, the alias
@yii represents the installation path of
the Yii framework;
@web represents the base URL for the currently running Web application.
Defining Aliases ¶
You can define an alias for a file path or URL by calling Yii::setAlias():
// an alias of a file path Yii::setAlias('@foo', '/path/to/foo'); // an alias of a URL Yii::setAlias('@bar', 'http://www.example.com'); // an alias of a concrete file that contains a \foo\Bar class Yii::setAlias('@foo/Bar.php', '/definitely/not/foo/Bar.php');
Note: The file path or URL being aliased may not necessarily refer to an existing file or resource.
Given a defined alias, you may derive a new alias (without the need of calling Yii::setAlias()) by appending
/ 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,
@foo/bar/file.php is a derived alias.
You can define an alias using another alias (either root or derived):
Root aliases are usually defined during the bootstrapping stage.
For example, you may call Yii::setAlias() in the entry script.
For convenience, Application provides a writable property named
that you can configure in the application configuration:
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 represents. The same method can also resolve a derived alias into the corresponding file path or URL:
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:
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
@foo/bar is not defined as a root alias, the last statement would display
Using Aliases ¶
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
and an alias representing a file path, thanks to the
@ prefix which allows it to differentiate a file path
from an alias.
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 easily reference commonly used file paths and URLs:
@yii, the directory where the
BaseYii.phpfile is located (also called the framework directory).
@app, the base path of the currently running application.
@runtime, the runtime path of the currently running application. Defaults to
@webroot, the Web root directory of the currently running Web application. It is determined based on the directory containing the entry script.
@web, the base URL of the currently running Web application. It has the same value as yii\web\Request::$baseUrl.
@vendor, the Composer vendor directory. Defaults to
@bower, the root directory that contains bower packages. Defaults to
@npm, the root directory that contains npm packages. Defaults to
@yii alias is defined when you include the
Yii.php file in your entry script.
The rest of the aliases are defined in the application constructor when applying the application
@webrootaliases as their descriptions indicate are defined within Web application and therefore are not available for Console application by default.
Extension Aliases ¶
An alias is automatically defined for each extension that is installed via Composer.
Each alias is named after the root namespace of the extension as declared in its
composer.json file, and each alias
represents the root directory of the package. For example, if you install the
you will automatically have the alias
@yii/jui defined during the bootstrapping stage, equivalent to: