Псевдоним пути и пространство имён
==================================

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

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

где `RootAlias` — псевдоним существующей директории.


При помощи [YiiBase::getPathOfAlias()] мы можем преобразовать псевдоним
в соответствующий ему путь. К примеру, `system.web.CController` будет
преобразован в `yii/framework/web/CController`.

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


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

Для удобства Yii предопределяет следующие системные псевдонимы:

 - `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 корневой псевдоним, указывающий на
корень модуля. К примеру, если приложение использует модуль `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 или выше.

Начиная с версии Yii 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`
так, как это описано далее в подразделе «Модули в пространствах имён».

Модули в пространствах имён
---------------------------

Иногда удобно использовать пространство имён для целого модуля. К примеру,
если вам необходимо использовать пространство имён `\mynamespace\modules\testmodule`,
расположенное в `/var/www/common/mynamespace/modules/testmodule`, для модуля `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',
		),
	),
~~~