Псевдонимы используются для представления путей или URL-адресов файлов, поэтому вам не нужно жестко закодировать абсолютные пути или URL-адреса в вашем проекте. Псевдоним должен начинаться с символа @, чтобы отличаться от обычных путей к файлам и URL-адресов. Псевдоним, определенный без @, будет иметь префикс с @ символом.

Yii уже имеет множество предопределенных псевдонимов. Например, псевдоним @yii представляет путь установки среды Yii; @web представляет базовый URL для текущего веб-приложения.

Определение псевдонимов

Вы можете определить псевдоним для пути к файлу или URL-адреса, вызывая 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');

Учитывая заданный псевдоним, вы можете получить новый псевдоним (без необходимости вызова 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');               // 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

Путь / URL-адрес, представленный производным псевдонимом, определяется путем замены части псевдонима корня его соответствующим путем / URL-адресом в производном псевдониме.

Псевдоним корня может также содержать косую черту / символы. Метод Yii::getAlias() достаточно умен, чтобы определить, какая часть псевдонима является корневым псевдонимом и, следовательно, правильно определяет соответствующий путь или 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 не определен как корневой псевдоним, последний оператор отображает /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 - базовый путь текущего приложения.
  • @runtime, путь выполнения текущего приложения. По умолчанию используется @app/runtime.
  • @webroot, корневой каталог Web текущего веб-приложения. Он определяется на основе каталога, содержащего сценарий входа.
  • @web, базовый URL текущего запущенного веб-приложения. Он имеет то же значение, что и yii\web\Request::$baseUrl.
  • @vendor, каталог поставщика Composer. По умолчанию используется @app/vendor.
  • @bower, корневой каталог, содержащий пакеты bower. По умолчанию используется @vendor/bower.
  • @npm, корневой каталог, содержащий пакеты npm. По умолчанию используется @vendor/npm.

Псевдоним @yii определяется, когда вы включаете файл Yii.php в свой сценарий ввода. Остальные псевдонимы определяются в конструкторе приложения при применении конфигурации приложения.

Псевдонимы добавочного номера

Псевдоним автоматически определяется для каждого расширения, которое установлено через Composer. Каждый псевдоним имеет имя корневого пространства имен расширения, объявленного в файле composer.json, и каждый псевдоним представляет корневой каталог пакета. Например, если вы установите расширение yiisoft/yii2-jui, вы автоматически получите псевдоним @yii/jui, определенный на этапе начальной загрузки, что эквивалентно:

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