yii/docs/guide/ja/topics.error.txt

エラーハンドリング
==============

YiiはPHP5の例外メカニズムを元にした完全なエラーハンドリングを提供します。
アプリケーションがユーザのリクエストによって呼び出された時、
アプリケーションは[handleError|CApplication::handleError]メソッドをPHP
warningとnoticeを扱うために登録し、
[handleException|CApplication::handleException]メソッドをPHP exeptions
(例外)を扱うために登録します。したがって、もしアプリケーションの実行時に
PHPのwarningやnotice、キャッチされない例外が発生した場合は、
エラーハンドラがコントロールを横取りし、必要なエラーハンドリングの処理を
開始します。

> Tip|ヒント: エラーハンドラは、アプリケーションのコンストラクタでPHP
ファンクションである
[set_exception_handler](http://php.net/manual/ja/function.set-exception-handler.php)
と
[set_error_handler](http://php.net/manual/ja/function.set-error-handler.php)
によって
登録されます。もし不要な場合は、[エントリスクリプト](/doc/guide/basics.entry)で
`YII_ENABLE_ERROR_HANDLER`と`YII_ENABLE_EXCEPTION_HANDLER`の定数をfalse
として定義する事で対応できます。

デフォルトでは、[handleError|CApplication::handleError] (または
[handleException|CApplication::handleException]) は
[onError|CApplication::onError]イベント
(または[onException|CApplication::onException]イベント) を発生させます。
これらは、もしエラー（あるいは例外）がイベントハンドラに全く
ハンドルされていない場合、[errorHandler|CErrorHandler]アプリケーション
コンポーネントから助けを呼びます。

例外の発生
------------------

Yiiでの例外は、PHPでの例外と同様です。以下の文法を例外を発生させる為に
使用できます:

~~~
[php]
throw new ExceptionClass('ExceptionMessage');
~~~

Yiiは三つの例外クラスを定義しています。[CException] 、[CDbException]、そして
[CHttpException] です。[CException] は包括的な例外クラスです。[CDbException] は
データベースに関係する何らかの操作によって引き起こされた例外を表します。
[CHttpException] はエンドユーザに表示されるべき例外を表すもので、
HTTP ステータスコードを表す [statusCode|CHttpException::statusCode] プロパティを
持っています。例外をどのように表示すべきかは、以下で説明するように、例外のクラスによって、
決ります。

> Tip|ヒント: [CHttpException]における例外の発生はユーザの入力ミスを
報告するのにシンプルな方法です。例えば、もしユーザが不正なpost IDのURLを
要求した場合、以下のように404error (page not found) をシンプルに表示する
事が出来ます:
~~~
[php]
// もし要求されたpost IDが不正な場合
throw new CHttpException(404,'The specified post cannot be found.');
~~~

エラーの表示
-----------------

エラーの処理が [CErrorHandler] アプリケーションコンポーネントまで
流れてくると、エラーを表示する為に相応しい ビュー が選ばれます。
もしエラーが[CHttpException]のように、エンドユーザへ表示するタイプの
ものだった場合、`errorXXX` といった様な名前の ビュー が使用され、この
`XXX` の部分はHTTPステータスコード(例えば400, 404, 500など)を表します。
もしエラーが内部的なもので、開発者にのみ表示するべきものであった場合、
`exeptions` という名前のビューが使用されます。その場合は、エラーの
起きている行番号をや完全なコールスタック(ファイルの階層情報など)が
表示されます。

> Info|情報: アプリケーションが [実運用モード](/doc/guide/basics.entry#sec-2) で実行された時、内部的なエラーを
含む全てのエラーは `errorXXX` という view を使用して表示されます。
こうなっているのは、エラーのコールスタックが機密に関わる情報を含む可能性が
ある為です。このモードでは、開発者はエラーの真の原因を究明する為に、
エラーログに頼ることになるでしょう。

[CErrorHandler] は下記の順序で対応する view ファイルを探します:

   1. `WebRoot/themes/ThemeName/views/system`: これは
現在アクティブになっているテーマの中の `system` ビューディレクトリです。

   2. `WebRoot/protected/views/system`: これはアプリケーションの
デフォルトの `system` ビューディレクトリです。

   3. `yii/framework/views`: これはYiiフレームワークによって供給される
標準のシステムビューディレクトリです。

したがって、もしエラーの表示をカスタマイズしたい場合は、アプリケーションか
テーマのシステムビューディレクトリーにエラービューファイルを作成する事で
容易に実現可能です。それぞれのビューファイルは、大部分がHTMLコードで
成り立った通常のPHPスクリプトです。詳細はframeworkの`view`ディレクトリの
デフォルトのビューファイルを参考にして下さい。

アクションを用いたエラーハンドリング
-------------------------------

Yiiでは[コントローラアクション](/doc/guide/basics.controller#sec-4)を用いてエラー表示をすることが出来ます。
これを行うために、アプリケーション構成ファイル中のエラーハンドラを以下のように構成します。

~~~
[php]
return array(
	......
	'components'=>array(
		'errorHandler'=>array(
			'errorAction'=>'site/error',
		),
	),
);
~~~

上記において、[CErrorHandler::errorAction]プロパティは`site/error`を示すように
します。これは`SiteController`コントローラの`error`アクションを意味します。
もし違う名前のコントローラ/アクションを使いたい場合はそれを用いても構いません。

`error`アクションは以下のように記述されます。

~~~
[php]
public function actionError()
{
	if($error=Yii::app()->errorHandler->error)
		$this->render('error', $error);
}
~~~

このアクションにおいて、最初に詳細なエラー情報を[CErrorHandler::error]から入手します。
もしこれが空でない場合は、このエラー情報にもとづき`error`ビューを表示します。
[CErrorHandler::error]で返されるエラー情報は以下のフィールドを持つ配列です。

 * `code`: HTTPステータスコード (例: 403, 500);
 * `type`: エラータイプ (例: [CHttpException], `PHP Error`);
 * `message`: エラーメッセージ
 * `file`: エラーの起きたPHPスクリプトファイル名
 * `line`: エラーの起きた行番号
 * `trace`: エラーのコールスタック
 * `source`: エラーの起きたソースコード

> Tip|ヒント: [CErrorHandler::error]が空であるかないかをチェックする理由は、`error`
アクションは、エラーが無い場合でもエンドユーザによって要求されることがあるためです。
`$error`配列をビューに渡す場合、それは自動的に個々の変数に展開されます。従って、ビューにおいては
それらの変数は例えば`$code`, `$type`のように直接アクセスすることができます。

メッセージのログ処理
---------------

エラーが発生した際、`error` レベルのメッセージは常に記録されます。
もしPHP warningかnoticeによってエラーが発生した場合、メッセージは
カテゴリー `php` と共に記録されます。もしエラーが
キャッチされていない例外として発生した際、カテゴリーは
`exception.ExceptionClassName`の様になるでしょう。
([CHttpException]における[statusCode|CHttpException::statusCode] もまた
カテゴリーに追加されるでしょう。) 
このようにアプリケーションの実行の間に起きるエラーをモニターする為の
[ロギング](/doc/guide/topics.logging)機能を利用することが出来ます。

<div class="revision">$Id: topics.error.txt 3374 2011-08-05 23:01:19Z alexander.makarow $</div>