Yii2教學 » 別名（Aliases）

別名（Aliases）

別名(Aliases)

別名用來表示檔案路徑和 URL，這樣就避免了在程式碼中寫死一些絕對路徑和 URL。一個別名必須以 @ 字元開頭，以區別於傳統的檔案路徑和 URL。Yii 預定義了大量可用的別名。例如，別名 @yii 指的是 Yii 框架本身的安裝目錄，而 @web 表示的是當前執行應用的根 URL。

定義別名

你可以呼叫 [[Yii::setAlias()]] 來給檔案路徑或 URL 定義別名：

  1. // 檔案路徑的別名 
  2. Yii::setAlias('@foo', '/path/to/foo'); 
  3.  
  4. // URL 的別名 
  5. Yii::setAlias('@bar', 'http://www.example.com');

注意：別名所指向的檔案路徑或 URL 不一定是真實存在的檔案或資源。

可以通過在一個別名後面加斜杠 / 和一至多個路徑分段生成新別名(無需呼叫 [[Yii::setAlias()]])。我們把通過 [[Yii::setAlias()]] 定義的別名稱為根別名，而用他們衍生出去的別名成為衍生別名。例如，@foo 就是跟別名，而 @foo/bar/file.php 是一個衍生別名。

你還可以用別名去定義新別名(根別名與衍生別名均可)：

  1. Yii::setAlias('@foobar', '@foo/bar');

根別名通常在引導階段定義。比如你可以在入口指令碼裡呼叫 [[Yii::setAlias()]]。為了方便起見，應用提供了一個名為 aliases 的可寫屬性，你可以在應用組態中設定它，就像這樣：

  1. return [ 
  2.     // ... 
  3.     'aliases' => [ 
  4.         '@foo' => '/path/to/foo', 
  5.         '@bar' => 'http://www.example.com', 
  6.     ], 
  7. ];

解析別名

你可以呼叫 [[Yii::getAlias()]] 命令來解析根別名到對應的檔案路徑或 URL。同樣的頁面也可以用於解析衍生別名。例如：

  1. echo Yii::getAlias('@foo');               // 輸出：/path/to/foo 
  2. echo Yii::getAlias('@bar');               // 輸出：http://www.example.com 
  3. echo Yii::getAlias('@foo/bar/file.php');  // 輸出：/path/to/foo/bar/file.php

由衍生別名所解析出的檔案路徑和 URL 是通過替換掉衍生別名中的根別名部分得到的。

注意：[[Yii::getAlias()]] 並不檢查結果路徑/URL 所指向的資源是否真實存在。

根別名可能也會包含斜槓 /。[[Yii::getAlias()]] 足夠智慧到判斷一個別名中的哪部分是根別名，因此能正確解析檔案路徑/URL。例如：

  1. Yii::setAlias('@foo', '/path/to/foo'); 
  2. Yii::setAlias('@foo/bar', '/path2/bar'); 
  3. echo Yii::getAlias('@foo/test/file.php');  // 輸出：/path/to/foo/test/file.php 
  4. 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]] 能同時接受檔案路徑或是指向檔案路徑的別名，因為通過 @ 字首能區分它們。

  1. use yii\\caching\\FileCache; 
  2.  
  3. $cache = new FileCache([ 
  4.     'cachePath' => '@runtime/cache', 
  5. ]);

請關注 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 別名，它定義於引導啟動階段：

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