エラー処理 ¶

Yii には、組み込みの エラーハンドラ が含まれており、以前よりもはるかに快適なエラー処理を実現します。特に、Yii のエラーハンドラは、エラー処理を改善するために次のことを行います。

• すべての非致命的な PHP エラー（警告、通知など）は、キャッチ可能な例外に変換されます。
• 例外と致命的な PHP エラーは、デバッグモードでは詳細なコールスタック情報とソースコード行とともに表示されます。
• エラーの表示に専用の コントローラーアクション を使用できます。
• さまざまなエラー応答形式をサポートしています。

エラーハンドラ はデフォルトで有効になっています。アプリケーションの エントリスクリプト で定数 YII_ENABLE_ERROR_HANDLER を false に定義することで、無効にすることができます。

エラーハンドラの使用 ¶

エラーハンドラ は、errorHandler という名前の アプリケーションコンポーネント として登録されています。次のようにアプリケーション設定で構成できます。

return [
    'components' => [
        'errorHandler' => [
            'maxSourceLines' => 20,
        ],
    ],
];

上記の構成では、例外ページに表示されるソースコード行数は最大 20 行になります。

前述のように、エラーハンドラはすべての非致命的な PHP エラーをキャッチ可能な例外に変換します。つまり、次のコードを使用して PHP エラーを処理できます。

use Yii;
use yii\base\ErrorException;

try {
    10/0;
} catch (ErrorException $e) {
    Yii::warning("Division by zero.");
}

// execution continues...

ユーザーのリクエストが無効または予期しないものであることを伝えるエラーページを表示したい場合は、HTTP 例外（yii\web\NotFoundHttpException など）をスローするだけです。エラーハンドラは、レスポンスの HTTP ステータスコードを正しく設定し、適切なエラービューを使用してエラーメッセージを表示します。

use yii\web\NotFoundHttpException;

throw new NotFoundHttpException();

エラー表示のカスタマイズ ¶

エラーハンドラ は、定数 YII_DEBUG の値に応じてエラー表示を調整します。YII_DEBUG が true の場合（デバッグモード）、エラーハンドラは詳細なコールスタック情報とソースコード行とともに例外を表示して、デバッグを容易にします。YII_DEBUG が false の場合、アプリケーションに関する機密情報を公開しないように、エラーメッセージのみが表示されます。

情報：例外が yii\base\UserException の子孫である場合、YII_DEBUG の値に関係なく、コールスタックは表示されません。これは、このような例外はユーザーのミスによって発生すると見なされ、開発者が修正する必要がないためです。

デフォルトでは、エラーハンドラは、2つのビューを使用してエラーを表示します。

• @yii/views/errorHandler/error.php：コールスタック情報なしでエラーを表示する場合に使用されます。YII_DEBUGがfalseの場合、これは表示される唯一のエラービューです。
• @yii/views/errorHandler/exception.php：コールスタック情報とともにエラーを表示する場合に使用されます。

エラーハンドラのerrorViewプロパティとexceptionViewプロパティを構成して、独自のビューを使用し、エラー表示をカスタマイズできます。

エラーアクションの使用 ¶

エラー表示をカスタマイズするより良い方法は、専用のエラーアクションを使用することです。そのためには、まず、次のようにerrorHandlerコンポーネントのerrorActionプロパティを構成します。

return [
    'components' => [
        'errorHandler' => [
            'errorAction' => 'site/error',
        ],
    ]
];

errorActionプロパティは、アクションへのルートを取ります。上記の構成では、コールスタック情報なしでエラーを表示する必要がある場合、site/errorアクションが実行されることを示しています。

site/errorアクションは、次のように作成できます。

namespace app\controllers;

use Yii;
use yii\web\Controller;

class SiteController extends Controller
{
    public function actions()
    {
        return [
            'error' => [
                'class' => 'yii\web\ErrorAction',
            ],
        ];
    }
}

上記のコードは、errorという名前のビューを使用してエラーをレンダリングするyii\web\ErrorActionクラスを使用してerrorアクションを定義しています。

yii\web\ErrorActionを使用することに加えて、次のようにアクションメソッドを使用してerrorアクションを定義することもできます。

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

views/site/error.phpにあるビューファイルを作成する必要があります。このビューファイルでは、エラーアクションがyii\web\ErrorActionとして定義されている場合、次の変数にアクセスできます。

• name：エラーの名前;
• message：エラーメッセージ;
• exception：HTTPステータスコード、エラーコード、エラーコールスタックなど、より有用な情報を取得できる例外オブジェクト。

情報：基本プロジェクトテンプレートまたは高度なプロジェクトテンプレートを使用している場合、エラーアクションとエラービューは既に定義されています。

注記：エラーハンドラでリダイレクトする必要がある場合は、次の方法で行います。

Yii::$app->getResponse()->redirect($url)->send();
return;

エラーレスポンス形式のカスタマイズ ¶

エラーハンドラは、レスポンスの形式設定に従ってエラーを表示します。レスポンス形式がhtmlの場合、前項で説明したように、エラービューまたは例外ビューを使用してエラーを表示します。他のレスポンス形式の場合、エラーハンドラは例外の配列表現をyii\web\Response::$dataプロパティに割り当て、その後、それに応じて異なる形式に変換します。たとえば、レスポンス形式がjsonの場合、次のレスポンスが表示される場合があります。

HTTP/1.1 404 Not Found
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
    "name": "Not Found Exception",
    "message": "The requested resource was not found.",
    "code": 0,
    "status": 404
}

アプリケーション構成でresponseコンポーネントのbeforeSendイベントに応答することで、エラーレスポンス形式をカスタマイズできます。

return [
    // ...
    'components' => [
        'response' => [
            'class' => 'yii\web\Response',
            'on beforeSend' => function ($event) {
                $response = $event->sender;
                if ($response->data !== null) {
                    $response->data = [
                        'success' => $response->isSuccessful,
                        'data' => $response->data,
                    ];
                    $response->statusCode = 200;
                }
            },
        ],
    ],
];

上記のコードは、エラーレスポンスを次のように再フォーマットします。

HTTP/1.1 200 OK
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
    "success": false,
    "data": {
        "name": "Not Found Exception",
        "message": "The requested resource was not found.",
        "code": 0,
        "status": 404
    }
}