パスエイリアスと名前空間
========================

Yii は広範囲に渡ってパスエイリアスを使用しています。
パスエイリアスは、ディレクトリまたはファイルパスと関連付けられます。
これは、広く採用されている名前空間の形式と同じように、ドットシンタックスで指定されます:

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

`RootAlias` の部分は既存の何らかのディレクトリに対するエイリアスです。


[YiiBase::getPathOfAlias()] を使うことより、エイリアスは対応するパスへ変換されます。
例えば、`system.web.CController` は `yii/framework/web/CController` のように変換されます。

また、[YiiBase::setPathOfAlias()] を用いて、新しいルートパスエイリアスを定義することもできます。

ルートエイリアス
----------------

便宜上、Yii は以下のルートエイリアスをあらかじめ定義しています。

 - `system`: Yii の framework ディレクトリを参照します。
 - `zii`: [Zii ライブラリ](/doc/guide/extension.use#sec-2) のディレクトリを参照します。
 - `application`: アプリケーションの [ベースディレクトリ](/doc/guide/basics.application#sec-3) を参照します。
 - `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_onde` や `require_once` よりも断然速いです。
ディレクトリをインポートする場合について、その下位ディレクトリはどれもインポートされないという点に注意して下さい。

> Tip|ヒント: Yii フレームワークで定義されたクラスを参照する場合、インポートやインクルードを行う必要はありません。
Yii の全てのコアクラスは、あらかじめインポートされています。

###クラスマップを使う

バージョン 1.1.5 からは、Yii コアクラスに使用されているクラスマッピング機構を、ユーザクラスをプリインポートするために使用可能になりました。
プリインポートされたクラスは 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` としてエイリアスされるファイルに格納される必要があります。

従って、例えば、`/var/www/common/mynamespace/` に存在するクラスに対して `\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 は `/var/www/common/mynamespace/controllers/TestController.php` に配置されている名前空間化クラス `\mynamespace\controllers\TestController` をロードします。

コントローラのコードは正しく名前空間化されていなければならないことに気を付けて下さい。

~~~
[php]
// 名前空間を定義:
namespace mynamespace\controllers;

// クラスは名前空間の下にあるので、グローバル名前空間は
// "\" を使って明示的に参照されなければならない:
class TestController extends \CController
{
	public function actionIndex()
	{
		echo 'これは \mynamespace\controllers の TestController です';
	}
}
~~~

### `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',
		),
	),
~~~

<div class="revision">$Id$</div>