エイリアス

ファイル・パスや 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');

// \foo\Bar クラスを保持する具体的なファイルのエイリアス
Yii::setAlias('@foo/Bar.php', '/definitely/not/foo/Bar.php');

Note: エイリアスされているファイル・パスや URL は、必ずしも実在するファイルまたはリソースを参照しない場合があります。

定義済みのエイリアスがあれば、スラッシュ / に続けて 1 つ以上のパス・セグメントを追加することで(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 を解決することができます。 同メソッドで、派生エイリアスを対応するファイル・パスまたは 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 は、 派生エイリアス内のルート・エイリアス部分を対応するパスや URL で置換して決定されます。

Note: Yii::getAlias() メソッドは、 結果のパスや URL が実在するファイルやリソースを参照しているかをチェックしません。

ルート・エイリアス名にはスラッシュ / 文字を含むことができます。 Yii::getAlias() メソッドは、 エイリアスのどの部分がルート・エイリアスであるかを賢く判別し、 正確に対応するファイル・パスや URL を決定します:

Yii::setAlias('@foo', '/path/to/foo');
Yii::setAlias('@foo/bar', '/path2/bar');
Yii::getAlias('@foo/test/file.php');  // /path/to/foo/test/file.php を表示
Yii::getAlias('@foo/bar/file.php');   // /path2/bar/file.php を表示

もし @foo/bar がルート・エイリアスとして定義されていなければ、最後のステートメントは /path/to/foo/bar/file.php を表示します。

エイリアスを使用する

Yii では、多くの場所で、パスや URL に変換する Yii::getAlias() を呼び出す必要なく、 エイリアスが認識されます。 たとえば、 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
  • @runtime, 現在実行中のアプリケーションの yii\base\Application::runtimePath 。デフォルトは @app/runtime
  • @webroot, 現在実行中のウェブ・アプリケーションのウェブ・ルート・ディレクトリ。 エントリス・クリプトを含むディレクトリによって決定されます。
  • @web, 現在実行中のウェブ・アプリケーションのベース URL。これは、 yii\web\Request::baseUrl と同じ値を持ちます。
  • @vendor, yii\base\Application::vendorPath 。デフォルトは @app/vendor
  • @bower, bower パッケージ が含まれるルート・ディレクトリ。デフォルトは @vendor/bower
  • @npm, npm パッケージ が含まれるルート・ディレクトリ。デフォルトは @vendor/npm

@yii エイリアスは エントリ・スクリプトYii.php ファイルを読み込んだ時点で定義されます。 エイリアスの残りの部分は、アプリケーションのコンストラクタ内で、アプリケーションの 構成情報 を適用するときに定義されます。

Note: @web@webroot のエイリアスは、その説明が示しているように、ウェブ・アプリケーション の中で定義されます。従って、デフォルトでは コンソール・アプリケーション では利用できません。

エクステンションのエイリアス

Composer でインストールされる エクステンション のそれぞれに対してエイリアスが自動的に定義されます。 各エイリアスは、その composer.json ファイルで宣言されたエクステンションのルート名前空間にちなんで名付けられ、 パッケージのルート・ディレクトリを表します。たとえば、あなたが yiisoft/yii2-jui エクステンションをインストールしたとすると、 自動的に @yii/jui というエイリアスが ブートストラップ 段階で定義されます。これは次のものと等価です。

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