別名(Aliases)
別名(Aliases)
別名用來表示文件路徑和 URL,這樣就避免了在代碼中硬編碼一些絕對路徑和 URL。一個別名必須以 @
字符開頭,以區別於傳統的文件路徑和 URL。Yii 預定義了大量可用的別名。例如,別名 @yii
指的是 Yii 框架本身的安裝目錄,而 @web
表示的是當前運行應用的根 URL。
定義別名
你可以調用 [[Yii::setAlias()]] 來給文件路徑或 URL 定義別名:
// 文件路徑的別名
Yii::setAlias('@foo', '/path/to/foo');
// URL 的別名
Yii::setAlias('@bar', 'http://www.example.com');
注意:別名所指向的文件路徑或 URL 不一定是真實存在的文件或資源。
可以通過在一個別名後面加斜槓 /
和一至多個路徑分段生成新別名(無需調用 [[Yii::setAlias()]])。我們把通過 [[Yii::setAlias()]] 定義的別名稱爲根別名,而用他們衍生出去的別名成爲衍生別名。例如,@foo
就是跟別名,而 @foo/bar/file.php
是一個衍生別名。
你還可以用別名去定義新別名(根別名與衍生別名均可):
- Yii::setAlias('@foobar', '@foo/bar');
根別名通常在引導階段定義。比如你可以在入口腳本裏調用 [[Yii::setAlias()]]。爲了方便起見,應用提供了一個名爲 aliases
的可寫屬性,你可以在應用配置中設置它,就像這樣:
- return [
- // ...
- 'aliases' => [
- '@foo' => '/path/to/foo',
- '@bar' => 'http://www.example.com',
- ],
- ];
解析別名
你可以調用 [[Yii::getAlias()]] 命令來解析根別名到對應的文件路徑或 URL。同樣的頁面也可以用於解析衍生別名。例如:
- echo Yii::getAlias('@foo'); // 輸出:/path/to/foo
- echo Yii::getAlias('@bar'); // 輸出:http://www.example.com
- echo Yii::getAlias('@foo/bar/file.php'); // 輸出:/path/to/foo/bar/file.php
由衍生別名所解析出的文件路徑和 URL 是通過替換掉衍生別名中的根別名部分得到的。
注意:[[Yii::getAlias()]] 並不檢查結果路徑/URL 所指向的資源是否真實存在。
根別名可能也會包含斜槓 /
。[[Yii::getAlias()]] 足夠智能到判斷一個別名中的哪部分是根別名,因此能正確解析文件路徑/URL。例如:
- Yii::setAlias('@foo', '/path/to/foo');
- Yii::setAlias('@foo/bar', '/path2/bar');
- echo Yii::getAlias('@foo/test/file.php'); // 輸出:/path/to/foo/test/file.php
- echo Yii::getAlias('@foo/bar/file.php'); // 輸出:/path2/bar/file.php
若 @foo/bar
未被定義爲根別名,最後一行語句會顯示爲 /path/to/foo/bar/file.php
。
使用別名
別名在 Yii 的很多地方都會被正確識別,無需調用 [[Yii::getAlias()]] 來把它們轉換爲路徑/URL。例如,[[yii\caching\FileCache::cachePath]] 能同時接受文件路徑或是指向文件路徑的別名,因爲通過 @
前綴能區分它們。
use yii\\caching\\FileCache;
$cache = new FileCache([
'cachePath' => '@runtime/cache',
]);
請關注 API 文檔瞭解特定屬性或方法參數是否支持別名。
預定義的別名
Yii 預定義了一系列別名來簡化常用路徑和 URL的使用:
- @yii - BaseYii.php 文件所在的目錄(也被稱爲框架安裝目錄)
- @app - 當前運行的應用 [[yii\base\Application::basePath|根路徑(base path)]]
- @runtime - 當前運行的應用的 [[yii\base\Application::runtimePath|運行環境(runtime)路徑]]
- @vendor - [[yii\base\Application::vendorPath|Composer 供應商目錄]]
- @webroot - 當前運行應用的 Web 入口目錄
- @web - 當前運行應用的根 URL
@yii
別名是在入口腳本裏包含 Yii.php
文件時定義的,其他的別名都是在配置應用的時候,於應用的構造方法內定義的。
擴展的別名
每一個通過 Composer 安裝的 擴展 都自動添加了一個別名。該別名會以該擴展在 composer.json
文件中所聲明的根命名空間爲名,且他直接代指該包的根目錄。例如,如果你安裝有 yiisoft/yii2-jui
擴展,會自動得到 @yii/jui
別名,它定義於引導啓動階段:
- Yii::setAlias('@yii/jui', 'VendorPath/yiisoft/yii2-jui');