concept-aliases.md 8.13 KB
Newer Older
zxcq544 committed
1
Псевдонимы 
2
=========
zxcq544 committed
3

4
Псевдонимы используются для обозначения путей к файлам или URL адресов и помогают избежать использования абсолютных путей
5
или URL в коде. Для того, чтобы не перепутать псевдоним с обычным путём к файлу или URL, он должен начинаться с `@`. В Yii
6 7
имеется множество заранее определённых псевдонимов. Например, `@yii` указывает на директорию, в которую был установлен
Yii framework, а `@web` можно использовать для получения базового URL текущего приложения.
zxcq544 committed
8 9 10


Создание псевдонимов <a name="defining-aliases"></a>
11
----------------------------------------------
zxcq544 committed
12

13
Для создания псевдонима пути к файлу или URL используется метод [[Yii::setAlias()]]:
zxcq544 committed
14 15 16 17 18

```php
// псевдоним пути к файлу
Yii::setAlias('@foo', '/path/to/foo');

19
// псевдоним URL
zxcq544 committed
20 21 22
Yii::setAlias('@bar', 'http://www.example.com');
```

23
> Примечание: псевдоним пути к файлу или URL *не* обязательно указывает на существующий файл или ресурс.
zxcq544 committed
24

25 26 27
Используя уже заданный псевдоним, вы можете получить на основе него новый без вызова [[Yii::setAlias()]]. Сделать это
можно, добавив в его конец `/`, за которым следует один или более сегментов пути. Псевдонимы, определённые при помощи
[[Yii::setAlias()]], являются *корневыми псевдонимами*, в то время как полученные из них называются *производными
28
псевдонимами*. К примеру, `@foo` является корневым псевдонимом, а `@foo/bar/file.php` — производным.
zxcq544 committed
29

30
Вы можете задать новый псевдоним, используя ранее созданный псевдоним (не важно, корневой он или производный):
zxcq544 committed
31 32 33 34 35

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

36 37 38 39
Корневые псевдонимы, как правило, создаются на этапе [предварительной загрузки (bootstrapping)](runtime-bootstrapping.md).
Например, вы можете вызвать [[Yii::setAlias()]] в [входном скрипте](structure-entry-scripts.md). Для удобства, в
[приложении (Application)](structure-applications.md) предусмотрено свойство `aliases`, которое можно задать через
[конфигурацию приложения](concept-configurations.md):
zxcq544 committed
40 41 42 43 44 45 46 47 48 49 50 51

```php
return [
    // ...
    'aliases' => [
        '@foo' => '/path/to/foo',
        '@bar' => 'http://www.example.com',
    ],
];
```


52 53
Преобразование псевдонимов <a name="resolving-aliases"></a>
----------------------------------------------------
zxcq544 committed
54

55
Метод [[Yii::getAlias()]] преобразует корневой псевдоним в путь к файлу или URL, который этот псевдоним представляет.
56
Этот же метод может работать и с производными псевдонимами:
zxcq544 committed
57 58 59 60 61 62 63

```php
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
```

64
Путь или URL, представленный производным псевдонимом, определяется путём замены в нём части, соответствующей корневому
65
псевдониму, на соответствующий ему путь или URL.
zxcq544 committed
66

67
> Примечание: Метод [[Yii::getAlias()]] не проверяет фактического существования получаемого пути или URL.
zxcq544 committed
68

69 70
Корневой псевдоним может содержать знаки '/'. При этом метод [[Yii::getAlias()]] корректно определит, какая часть
псевдонима является корневой и верно сформирует путь или URL:
zxcq544 committed
71 72 73 74 75 76 77 78

```php
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
```

79
Если бы `@foo/bar` не был объявлен корневым псевдонимом, последняя строка вывела бы  `/path/to/foo/bar/file.php`.
zxcq544 committed
80 81 82


Использование псевдонимов <a name="using-aliases"></a>
83
------------------------------------------------
zxcq544 committed
84

85 86 87
Псевдонимы распознаются во многих частях Yii без необходимости предварительно вызывать [[Yii::getAlias()]] для
получения пути или URL. Например, [[yii\caching\FileCache::cachePath]] принимает как обычный путь к файлу, так и
псевдоним пути благодаря префиксу `@`, который позволяет их различать.
zxcq544 committed
88 89 90 91 92 93 94 95 96

```php
use yii\caching\FileCache;

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

97
Для того, чтобы узнать поддерживает ли метод или свойство псевдонимы, обратитесь к документации API.
zxcq544 committed
98 99


100 101
Заранее определённые псевдонимы <a name="predefined-aliases"></a>
----------------------------------------------------------
zxcq544 committed
102

103
В Yii заранее определны псевдонимы для часто используемых путей к файлам и URL:
zxcq544 committed
104

105 106 107 108 109 110
- `@yii`: директория, в которой находится файл `BaseYii.php` (директория фреймворка).
- `@app`: [[yii\base\Application::basePath|базовый путь]] текущего приложения.
- `@runtime`: [[yii\base\Application::runtimePath|директория runtime]] текущего приложения.
- `@vendor`: [[yii\base\Application::vendorPath|директория vendor Composer].
- `@webroot`: вебрут текущего веб приложения (там где `index.php`).
- `@web`: базовый URL текущего приложения.
zxcq544 committed
111

112
Псевдоним `@yii` задаётся в момент подключения файла `Yii.php` во [входном скрипте](structure-entry-scripts.md).
113
Остальные псевдонимы задаются в конструкторе приложения в момент применения [конфигурации](concept-configurations.md).
zxcq544 committed
114 115 116


Псевдонимы расширений <a name="extension-aliases"></a>
117
------------------------------------------------
zxcq544 committed
118

119 120 121 122 123
Для каждого [расширения](structure-extensions.md), устанавливаемого через Composer, автоматически задаётся псевдоним.
Его имя соответствует корневому пространству имён расширения в соответствии с его `composer.json`. Псевдоним представляет
путь к корневой директории пакета. Например, если вы установите расширение `yiisoft/yii2-jui`, то вам автоматически станет
доступен псевдоним `@yii/jui`. Он создаётся на этапе [первоначальной загрузки (bootstrapping)](runtime-bootstrapping.md)
примерно так:
zxcq544 committed
124 125 126 127

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