Aliases (Apelidos) ¶

Aliases são usados para representar caminhos de arquivos ou URLs de forma que você não precise acoplar o código usando caminhos absolutos ou URLs em seu projeto. Um alias deve começar com o caractere @ para se diferenciar de um caminho de arquivo normal ou URL. O Yii já possui vários aliases predefinidos disponíveis. Por exemplo, o alias @yii representa o local em que o framework Yii foi instalado; @web representa a URL base para a aplicação que está sendo executada no momento.

Definindo Aliases ¶

Você pode definir um alias para um caminho de arquivo ou URL chamando Yii::setAlias():

// um alias de um caminho de arquivo
Yii::setAlias('@foo', '/caminho/para/foo');

// um alias de uma URL
Yii::setAlias('@bar', 'https://www.exemplo.com.br');

Observação: O caminho do arquivo ou URL sendo apelidado (aliased) não necessariamente refere-se a um arquivo ou a recursos existentes.

Dado um alias definido, você pode derivar um novo alias (sem a necessidade de chamar Yii::setAlias()) apenas acrescentando uma barra / seguido de um ou mais segmentos de caminhos de arquivos. Os aliases definidos através de Yii::setAlias() tornam-se o alias raiz (root alias), enquanto que aliases derivados dele, tornam-se aliases derivados. Por exemplo, @foo é um alias raiz (root alias), enquanto @foo/bar/arquivo.php é um alias derivado.

Você pode definir um alias usando outro alias (tanto raiz quanto derivado):

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

Aliases raiz são normalmente definidos durante o estágio de inicialização. Por exemplo, você pode chamar Yii::setAlias() no script de entrada. Por conveniência, as aplicações difinem uma propriedade aliases que você pode configurar na configuração da aplicação:

return [
    // ...
    'aliases' => [
        '@foo' => '/caminho/para/foo',
        '@bar' => 'https://www.exemplo.com.br',
    ],
];

Resolvendo Aliases ¶

Você pode chamar Yii::getAlias() em um alias raiz para resolver o caminho de arquivo ou URL que ele representa. O mesmo método pode resolver também um alias derivado em seu caminho de arquivo ou URL correspondente.

echo Yii::getAlias('@foo');               // exibe: /caminho/para/foo
echo Yii::getAlias('@bar');               // exibe: https://www.example.com
echo Yii::getAlias('@foo/bar/arquivo.php');  // exibe: /caminho/para/foo/bar/arquivo.php

O caminho/URL representado por um alias derivado é determinado substituindo a parte do alias raiz com o seu caminho/URL correspondente.

Observação: O método Yii::getAlias() não checa se o caminho/URL resultante refere-se a um arquivo ou recursos existentes.

Um alias raiz pode também conter caracteres de barra /. O método Yii::getAlias() é inteligente o suficiente para descobrir que parte de um alias é um alias raiz e assim determina o caminho de arquivo ou URL correspondente:

Yii::setAlias('@foo', '/caminho/para/foo');
Yii::setAlias('@foo/bar', '/caminho2/bar');
Yii::getAlias('@foo/test/arquivo.php');  // exibe: /caminho/para/foo/test/arquivo.php
Yii::getAlias('@foo/bar/arquivo.php');   // exibe: /caminho2/bar/arquivo.php

Se @foo/bar não estivesse definido como um alias raiz, a última chamada exibiria /caminho/para/foo/bar/arquivo.php.

Usando Aliases ¶

Aliases são reconhecidos em muitos lugares no Yii sem a necessidade de chamar Yii::getAlias() para convertê-los em caminhos e URLs. Por exemplo, yii\caching\FileCache::$cachePath pode aceitar tanto um caminho de arquivo quanto um alias representando o caminho do arquivo, graças ao prefíxo @ que nos permite diferenciar um caminho de arquivo de um alias.

use yii\caching\FileCache;

$cache = new FileCache([
    'cachePath' => '@runtime/cache',
]);

Por favor, consulte a documentação da API para saber se o parâmetro de uma propriedade ou método suporta aliases.

Aliases Predefinidos ¶

O Yii já predefine uma gama de aliases para referenciar facilmente caminhos de arquivos e URLs comumente usados:

• @yii, o diretório onde o arquivo BaseYii.php está localizado (também chamado de diretório do framework).
• @app, o caminho base da aplicação sendo executada no momento.
• @runtime, o caminho runtime da aplicação sendo executada no momento.
• @webroot, o diretório webroot da aplicação sendo executada no momento. Este é determinado baseado no diretório contendo o script de entrada.
• @web, a URL base da aplicacão sendo executada no momento. Esta tem o mesmo valor de yii\web\Request::$baseUrl.
• @vendor, o caminho da pasta vendor do Composer. Seu padrão é @app/vendor.
• @bower, o caminho raiz que contém os pacotes bower. Seu padrão é @vendor/bower.
• @npm, o caminho raiz que contém pacotes npm. Seu padrão é @vendor/npm.

O alias @yii é definido quando você inclui o arquivo Yii.php em seu script de entrada. O resto dos aliases são definidos no construtor da aplicação ao aplicar a configuração da aplicação.

Aliases para Extensões ¶

Um alias é automaticamente definido para cada extensão que for instalada através do Composer. Cada alias é nomeado a partir do namespace raiz da extensão como declarada em seu arquivo composer.json, e cada alias representa o diretório raiz de seu pacote. Por exemplo, se você instalar a extensão yiisoft/yii2-jui, você terá automaticamente o alias @yii/jui definido durante o estágio de inicialização, equivalente a:

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