Псевдонім маршруту та простір імен
==================================

Псевдоніми шляху широко використовуються в Yii.
Псевдонім асоціюється із директорією або шляхом до файлу.
При його вказуванні використовується точковий синтаксис, 
подібний із широко використовуваним форматом просторів імен:

~~~
RootAlias.path.to.target
~~~

де `RootAlias` — псевдонім існуючої директорії.


За допомого [YiiBase::getPathOfAlias()] ми можемо перетворити псевдонім
у відповідний йому шлях. наприклад, `system.web.CController` буде
перетворений у `yii/framework/web/CController`.

Також, ми можемо використовувати [YiiBase::setPathOfAlias()] для визначення нових
кореневих псевдонімів.


Кореневий псевдонім
-------------------

Для зручності, наступні системні псевдоніми вже визначені:

 - `system`: відповідає директорії фреймворка;
 - `zii`: відповідає директорії [бібліотеки розширень Zii](/doc/guide/extension.use#zii-extensions);
 - `application`: відповідає [базовій директорії додатку](/doc/guide/basics.application#application-base-directory);
 - `webroot`: відповідає директорії, яка містить [вхідний скрипт](/doc/guide/basics.entry).
 - `ext`: відповідає директорії, яка містить всі сторонні [розширення](/doc/guide/extension.overview).


Крім того, якщо додаток використовує [модулі](/doc/guide/basics.module), то
у кожного модуля є співпадаючий з його ID кореневий псевдонім, який вказує на
корінь модуля. Наприклад, якщо додаток використовує модуль з ID `users`, то буде
визначений кореневий псевдонім `users`.

Імпорт класів
-------------

Використовуючи псевдоніми, дуже зручно імпортувати описи класів.
Наприклад, для підключення класа [CController] можна викликати:

~~~
[php]
Yii::import('system.web.CController');
~~~

Використання методу [import|YiiBase::import] більш ефективно, ніж `include` та `require`, оскільки
опис імпортуємого класу не буде включено до першого звертання (реалізовано через механізм
автозавантаження класів PHP). Імпорт одного і того ж простору імен також відбувається набагато швидше, 
ніж при використанні `include_once` та `require_once`.
Зверніть увагу, що імпорт каталогу не імпортує будь-який із його підкаталогів.

> Tip|Підказка: Якщо ми посилаємося на клас фреймворку, то немає необхідності імпортувати або включати їх.
Всі системні класи Yii уже імпортовані заздалегідь.

### Використання таблиці класів

Починаючи із версії 1.1.5, Yii дозволяє попередньо імпортувати класи 
через той же механізм, що використовується для класів ядра. Такі класи
можуть використовуватися де завгодно у додатку без необхідності іх попереднього
імпорту або підключення. Дана можливість відмінно підходить для фреймворку або бібліотеки,
які використовує Yii.

Для імпорту набору класів, виконайте наступний код до виклику [CWebApplication::run()]:

~~~
[php]
Yii::$classMap=array(
	'ClassName1' => 'path/to/ClassName1.php',
	'ClassName2' => 'path/to/ClassName2.php',
	......
);
~~~


Імпорт директорій
-----------------

Можна використовувати наступний синтаксис для того, щоб імпортувати цілу директорію, а файли класів,
які містяться у директорії, будуть підключені автоматично при необхідності.

~~~
[php]
Yii::import('system.web.*');
~~~

Окрім [import|YiiBase::import], псевдоніми також використовуються у багатьох інших місцях, 
де є посилання на класи. Наприклад, псевдонім може бути переданий методу [Yii::createComponent()] 
для створення екземпляру відповідного класу, навіть якщо цей клас не був попередньо включений.

Простір імен
------------

Простори служать для логічного групування імен класів, 
щоб їх можна було відрізнити від інших, навіть якщо їх імена співпадають.
Не плутайте псевдонім шляху із простором імен. Псевдонім шляху — всього навсього
зручний спосіб іменування файлів та директорій. До простору імен він не має ніякого
відношення.

> Tip|Підказка: Так як версії PHP до 5.3.0 не підтримують простори імен, ви не можете створити
екземпляри класів з однаковими іменами, аде різними описами. По цій причині всі назви
класів  Yii-фреймворка мають префікс 'C' (який означає 'class'), щоб їх можна було відрізнити від
користувальницьких класів. Для користувальницьких класів рекомендується використовувати інші префікси,
зберігши префікс 'C' зарезервованим для Yii-фреймворка.

Класи у просторах імен
----------------------

Клас у просторі імен — будь-який клас, описаний у неглобальному просторі імен.
Наприклад, клас `application\components\GoogleMap` описаний у просторі імен
`application\components`. Використання простору імен вимагає PHP 5.3.0 і вище.

Починаючи із версії 1.1.5 стало можливим використання класу з простору імен
без його попереднього підключення. Наприклад, ми можемо створити новий екземпляр
`application\components\GoogleMap` без явного підключення відповідного файлу.
Це реалізується за допомогою покращеного завантажувача класів Yii.

Для того, щоб автоматично довантажити клас із простору імен, простір імен повинен бути
названий у тому ж стилі, що і псевдоніми шляхів. Наприклад, клас `application\components\GoogleMap`
повинен зберігатися у файлі, якому відповідає псевдонім `application.components.GoogleMap`.

Таким чином, для використання користувальницьких просторів імен, 
що починаються, наприклад із `\mynamespace`, де класи розташовані у `/var/www/common/mynamespace/`,
єдине, що ви повинні зробити це визначити шлях псевдоніму, як наприклад:

~~~
[php]
Yii::setPathOfAlias('mynamespace', '/var/www/common/mynamespace/');
~~~

Контролери у просторах імен
---------------------------

За замовчуванням Yii використовує контролери із глобального простору імен. 
Ці класи знаходяться у `protected/controllers`.
Ви можете змінити дану поведінку двома способами: 
використовуючи `controllerMap` та використовуючи `controllerNamespace`.
Перший дозволяє використовувати контролери із різних просторів імен.
Другий легше налаштовується, але задає один простір імен для всіх контролерів.

### Використання `controllerMap`

Краще всього змінювати дану властивість через файл конфігурації (`protected/config/main.php`):

~~~
[php]
// додаємо простір імен "mynamespace"
Yii::setPathOfAlias('mynamespace', '/var/www/common/mynamespace/');

return array(
	'basePath'=>dirname(__FILE__).DIRECTORY_SEPARATOR.'..',
	'name'=>'My Web Application',

	'controllerMap' => array(
		'test' => '\mynamespace\controllers\TestController',
	),
~~~

Коли користувач намагається завантажити будь-який із контролерів, визначених у `controllerMap`,
Yii завантажує вказані класи, минаючи звичайний метод завантаження контролера.
У випадку із `test`, Yii буде завантажувати класс із простору імен
`\mynamespace\controllers\TestController` розташованного у
`/var/www/common/mynamespace/controllers/TestController.php`.

Зверніть увагу, що код контролера повинен бути належним чином призначений до простору імен:

~~~
[php]
// визначаємо простір імен:
namespace mynamespace\controllers;

// відколи клас тепер знаходиться у просторі імен, звертання до глобального простору імен
// повинно відбуватися явно із використанням "\":
class TestController extends \CController
{
	public function actionIndex()
	{
		echo 'Це TestController із \mynamespace\controllers';
	}
}
~~~

### Використання `controllerNamespace`

Так як додаток є модулем, то ви можете використовувати `controllerNamespace`
так, як це описано далі у підрозділі "Модулі у просторах імен".

Модулі у просторах імен
-----------------------

Іноді корисно визначити простір імен для цілого модуля. 
Наприклад, якщо ви хочете помістити `testmodule` у простір імен `\mynamespace\modules\testmodule`, який вказує на
`/var/www/common/mynamespace/modules/testmodule`, вам потрібно спочатку створити наступну файлову структуру:

~~~
/var/www/common/mynamespace/modules
  testmodule
    controllers
      DefaultController.php
    views
      default
        index.php
    TestmoduleModule.php
~~~

Представлення `index.php` таке саме, як і у звичайного модуля.
`TestmoduleModule.php` та `DefaultController.php` знаходяться у просторі імен.

`TestmoduleModule.php`:

~~~
[php]
// визначаємо простір імен:
namespace mynamespace\modules\testmodule;

// відколи клас тепер знаходиться у просторі імен, звертання до глобального простору імен
// повинно відбуватися явно із використанням "\":
class TestmoduleModule extends \CWebModule
{
	// налаштування неглобального простору імен контролерів (також можна зробити за допомогою конфігурації)
	public $controllerNamespace = '\mynamespace\modules\testmodule\controllers';

	// звичайний код модуля
}
~~~

`DefaultController.php`:

~~~
[php]
<?php
// визначаємо простір імен:
namespace mynamespace\modules\testmodule\controllers;

// відколи клас тепер знаходиться у просторі імен, звертання до глобального простору імен
// повинно відбуватися явно із використанням "\":
class DefaultController extends \Controller
{
	public function actionIndex()
	{
		$this->render('index');
	}
}
~~~

Тепер залишилося тільки додати наш модуль до додатку. 
Найкращий спосіб зробити це, щоб вказати його у файлі конфігурації додатку (`protected/config/main.php`):

~~~
[php]
// додаємо простір імен "mynamespace"
Yii::setPathOfAlias('mynamespace', '/var/www/common/mynamespace/');

return array(
	'basePath'=>dirname(__FILE__).DIRECTORY_SEPARATOR.'..',
	'name'=>'My Web Application',

	'modules'=>array(
		'testmodule' => array(
			'class' => '\mynamespace\modules\testmodule\TestModuleModule',
		),
	),
~~~