Laravel 9.x エラー処理

イントロダクションIntroduction

エラーと例外の処理は、新しいLaravelプロジェクトの開始時に最初から設定されています。App\Exceptions\Handlerクラスは、アプリケーションが投げるすべての例外がログに記録され、ユーザーへレンダする場所です。このドキュメント全体を通して、このクラスについて詳しく説明します。When you start a new Laravel project, error and exception handling is already configured for you. The App\Exceptions\Handler class is where all exceptions thrown by your application are logged and then rendered to the user. We'll dive deeper into this class throughout this documentation.

設定Configuration

config/app.php設定ファイルのdebugオプションは、エラーに関する情報が実際にユーザーに表示される量を決定します。デフォルトでは、このオプションは、.envファイルに保存されているAPP_DEBUG環境変数の値を尊重するように設定されています。The debug option in your config/app.php configuration file determines how much information about an error is actually displayed to the user. By default, this option is set to respect the value of the APP_DEBUG environment variable, which is stored in your .env file.

ローカル開発中は、APP_DEBUG環境変数をtrueに設定する必要があります。実稼働環境では、この値は常にfalseである必要があります。本番環境で値がtrueに設定されていると、機密性の高い設定値がアプリケーションのエンドユーザーに公開されるリスクが起きます。During local development, you should set the APP_DEBUG environment variable to true. In your production environment, this value should always be false. If the value is set to true in production, you risk exposing sensitive configuration values to your application's end users.

例外ハンドラThe Exception Handler

例外のレポートReporting Exceptions

すべての例外は、App\Exceptions\Handlerクラスが処理します。このクラスは、カスタム例外レポートとレンダリングコールバックを登録できるregisterメソッドを持っています。こうした各概念について詳しく説明します。例外レポートは、例外をログに記録したり、Flare、Bugsnag、Sentryなどの外部サービスへ送信したりするために使用します。デフォルトで例外はログ設定に基づいてログに記録します。ただし、必要に応じて例外を自由に記録できます。All exceptions are handled by the App\Exceptions\Handler class. This class contains a register method where you may register custom exception reporting and rendering callbacks. We'll examine each of these concepts in detail. Exception reporting is used to log exceptions or send them to an external service like Flare[https://flareapp.io], Bugsnag[https://bugsnag.com] or Sentry[https://github.com/getsentry/sentry-laravel]. By default, exceptions will be logged based on your logging[/docs/{{version}}/logging] configuration. However, you are free to log exceptions however you wish.

たとえば、さまざまなタイプの例外をさまざまな方法で報告する必要がある場合は、reportableメソッドを使用して、特定のタイプの例外を報告する必要があるときに実行するクロージャを登録できます。Laravelは、クロージャのタイプヒントを調べることで、クロージャが報告する例外のタイプを推測します。For example, if you need to report different types of exceptions in different ways, you may use the reportable method to register a closure that should be executed when an exception of a given type needs to be reported. Laravel will deduce what type of exception the closure reports by examining the type-hint of the closure:

use App\Exceptions\InvalidOrderException;

/**
 * アプリケーションの例外処理コールバックを登録
 *
 * @return void
 */
public function register()
{
    $this->reportable(function (InvalidOrderException $e) {
        //
    });
}

reportableメソッドを使用してカスタム例外レポートコールバックを登録した場合でも、Laravelはアプリケーションのデフォルトのログ設定を使用して例外をログに記録します。デフォルトのログスタックへ例外の伝播を停止する場合は、レポートコールバックを定義するときにstopメソッドを使用するか、コールバックからfalseを返します。When you register a custom exception reporting callback using the reportable method, Laravel will still log the exception using the default logging configuration for the application. If you wish to stop the propagation of the exception to the default logging stack, you may use the stop method when defining your reporting callback or return false from the callback:

$this->reportable(function (InvalidOrderException $e) {
    //
})->stop();

$this->reportable(function (InvalidOrderException $e) {
    return false;
});

lightbulb Note:特定の例外のレポートをカスタマイズするには、レポート可能な例外を利用することもできます。Note
To customize the exception reporting for a given exception, you may also utilize reportable exceptions[/docs/{{version}}/errors#renderable-exceptions].

グローバルログコンテキストGlobal Log Context

利用可能な場合、Laravelは現在のユーザーのIDをコンテキストデータとしてすべての例外のログメッセージに自動的に追加します。アプリケーションのApp\Exceptions\Handlerクラスのcontextメソッドをオーバーライドすることで、独自のグローバルコンテキストデータを定義できます。この情報は、アプリケーションによって書き込まれるすべての例外のログメッセージに含まれます。If available, Laravel automatically adds the current user's ID to every exception's log message as contextual data. You may define your own global contextual data by overriding the context method of your application's App\Exceptions\Handler class. This information will be included in every exception's log message written by your application:

/**
 * ログ用のデフォルトのコンテキスト変数を取得
 *
 * @return array
 */
protected function context()
{
    return array_merge(parent::context(), [
        'foo' => 'bar',
    ]);
}

例外ログコンテキストException Log Context

すべてのログメッセージにコンテキストを追加することは便利ですが、特定の例外にはログに含めたい固有のコンテキストがある場合もあります。アプリケーションのカスタム例外にcontextメソッドを定義することで、例外のログエントリに追加すべき、その例外に関連するデータを指定することができます。While adding context to every log message can be useful, sometimes a particular exception may have unique context that you would like to include in your logs. By defining a context method on one of your application's custom exceptions, you may specify any data relevant to that exception that should be added to the exception's log entry:

<?php

namespace App\Exceptions;

use Exception;

class InvalidOrderException extends Exception
{
    // ...

    /**
     * 例外のコンテキスト情報を取得
     *
     * @return array
     */
    public function context()
    {
        return ['order_id' => $this->orderId];
    }
}

reportヘルパThe report Helper

場合により、例外を報告する必要はあるが、現在のリクエストの処理を続行する必要がある場合もあります。reportヘルパ関数を使用すると、エラーページをユーザーに表示せずに、例外ハンドラを介して例外をすばやく報告できます。Sometimes you may need to report an exception but continue handling the current request. The report helper function allows you to quickly report an exception via the exception handler without rendering an error page to the user:

public function isValid($value)
{
    try {
        // 値のバリデーション…
    } catch (Throwable $e) {
        report($e);

        return false;
    }
}

例外のログレベルException Log Levels

アプリケーションのログにメッセージが書き込まれるとき、そのメッセージは指定されたログレベルで書かれ、これは書き込まれるメッセージの緊急度や重要度を表します。When messages are written to your application's logs[/docs/{{version}}/logging], the messages are written at a specified log level[/docs/{{version}}/logging#log-levels], which indicates the severity or importance of the message being logged.

前記のように、reportableメソッドを使用してカスタム例外レポートコールバックを登録した場合でも、Laravelはアプリケーションのデフォルトログ設定を使用して例外を記録します。しかし、ログレベルはメッセージを記録するチャンネルへ影響を与えることがあるため、特定の例外を記録するログレベルを設定したいでしょう。As noted above, even when you register a custom exception reporting callback using the reportable method, Laravel will still log the exception using the default logging configuration for the application; however, since the log level can sometimes influence the channels on which a message is logged, you may wish to configure the log level that certain exceptions are logged at.

そのため、アプリケーションの例外ハンドラの$levelsプロパティで、例外の種類と関連するログレベルの配列を定義できます。To accomplish this, you may define an array of exception types and their associated log levels within the $levels property of your application's exception handler:

use PDOException;
use Psr\Log\LogLevel;

/**
 * 例外タイプと関係するカスタムログレベルのリスト
 *
 * @var array<class-string<\Throwable>, \Psr\Log\LogLevel::*>
 */
protected $levels = [
    PDOException::class => LogLevel::CRITICAL,
];

タイプによる例外の無視Ignoring Exceptions By Type

アプリケーションを構築するときに、単に無視するだけで報告したくないタイプの例外もいくつかあるでしょう。アプリケーションの例外ハンドラには、空の配列に初期化されている$dontReportプロパティが含まれています。このプロパティに追加したクラスは報告されません。ただし、カスタムレンダリングロジックがある場合もあります。When building your application, there will be some types of exceptions you simply want to ignore and never report. Your application's exception handler contains a $dontReport property which is initialized to an empty array. Any classes that you add to this property will never be reported; however, they may still have custom rendering logic:

use App\Exceptions\InvalidOrderException;

/**
 * レポートしない例外タイプのリスト
 *
 * @var array<int, class-string<\Throwable>>
 */
protected $dontReport = [
    InvalidOrderException::class,
];

lightbulb Note:Laravelは、404 HTTP "not found"エラーや無効なCSRFトークンによって生成された419 HTTPレスポンスに起因する例外など、いくつかのタイプのエラーを皆さんのために裏でこっそり無視しています。Note
Behind the scenes, Laravel already ignores some types of errors for you, such as exceptions resulting from 404 HTTP "not found" errors or 419 HTTP responses generated by invalid CSRF tokens.

例外のレンダRendering Exceptions

デフォルトでは、Laravel例外ハンドラは例外をHTTPレスポンスへ変換します。ただし、特定タイプの例外に対して、カスタムレンダリングクロージャを自由に登録できます。これは、例外ハンドラのrenderableメソッドを介して実行します。By default, the Laravel exception handler will convert exceptions into an HTTP response for you. However, you are free to register a custom rendering closure for exceptions of a given type. You may accomplish this via the renderable method of your exception handler.

renderableメソッドへ渡すクロージャは、Responseヘルパを介して生成されるIlluminate\Http\Responseのインスタンスを返す必要があります。Laravelは、クロージャのタイプヒントを調べることで、どのタイプの例外をクロージャがレンダするのか推測します。The closure passed to the renderable method should return an instance of Illuminate\Http\Response, which may be generated via the response helper. Laravel will deduce what type of exception the closure renders by examining the type-hint of the closure:

use App\Exceptions\InvalidOrderException;

/**
 * アプリケーションの例外処理コールバックを登録
 *
 * @return void
 */
public function register()
{
    $this->renderable(function (InvalidOrderException $e, $request) {
        return response()->view('errors.invalid-order', [], 500);
    });
}

また、renderableメソッドを使い、NotFoundHttpExceptionなどのLaravelやSymfonyの組み込み例外のレンダ動作をオーバーライドすることもできます。renderableメソッドに指定したクロージャが値を返さない場合は、Laravelのデフォルト例外レンダが利用されます。You may also use the renderable method to override the rendering behavior for built-in Laravel or Symfony exceptions such as NotFoundHttpException. If the closure given to the renderable method does not return a value, Laravel's default exception rendering will be utilized:

use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

/**
 * アプリケーションの例外処理コールバックを登録
 *
 * @return void
 */
public function register()
{
    $this->renderable(function (NotFoundHttpException $e, $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => 'Record not found.'
            ], 404);
        }
    });
}

Reportable／Renderable例外Reportable & Renderable Exceptions

例外ハンドラのregisterメソッドで例外を型チェックする代わりに、カスタム例外に直接reportメソッドとrenderメソッドを定義することもできます。これらのメソッドが存在する場合、フレームワークによって自動的に呼び出されます。Instead of type-checking exceptions in the exception handler's register method, you may define report and render methods directly on your custom exceptions. When these methods exist, they will be automatically called by the framework:

<?php

namespace App\Exceptions;

use Exception;

class InvalidOrderException extends Exception
{
    /**
     * 例外を報告
     *
     * @return bool|null
     */
    public function report()
    {
        //
    }

    /**
     * 例外をHTTPレスポンスへレンダリング
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\Response
     */
    public function render($request)
    {
        return response(/* ... */);
    }
}

LaravelやSymfonyの組み込み済み例外など、既存のレンダリング可能な例外を拡張している場合は、例外のrenderメソッドからfalseを返し、例外のデフォルトHTTPレスポンスをレンダできます。If your exception extends an exception that is already renderable, such as a built-in Laravel or Symfony exception, you may return false from the exception's render method to render the exception's default HTTP response:

/**
 * Render the exception into an HTTP response.
 *
 * @param  \Illuminate\Http\Request  $request
 * @return \Illuminate\Http\Response
 */
public function render($request)
{
    // 例外がカスタムレンダリングを必要とするか判定…

    return false;
}

特定の条件が満たされた場合にのみ必要なカスタムレポートロジックが例外に含まれている場合は、デフォルトの例外処理設定を使用して例外をレポートするようにLaravelに指示する必要が起き得ます。これを行うには、例外のreportメソッドからfalseを返します。If your exception contains custom reporting logic that is only necessary when certain conditions are met, you may need to instruct Laravel to sometimes report the exception using the default exception handling configuration. To accomplish this, you may return false from the exception's report method:

/**
 * 例外を報告
 *
 * @return bool|null
 */
public function report()
{
    // 例外にカスタムレポートが必要かどうかを判定…

    return false;
}

lightbulb Note:reportメソッドで必要な依存関係をタイプヒントすると、Laravelのサービスコンテナがメソッドへ自動的に依存を注入します。Note
You may type-hint any required dependencies of the report method and they will automatically be injected into the method by Laravel's service container[/docs/{{version}}/container].

HTTP例外HTTP Exceptions

一部の例外は、サーバからのHTTPエラーコードを表します。たとえば、「ページが見つかりません」エラー(404)、「不正なエラー」(401)、または開発者が500エラーを生成する可能性もあります。アプリケーションのどこからでもこのようなレスポンスを生成したい場合は、abortヘルパを使用できます。Some exceptions describe HTTP error codes from the server. For example, this may be a "page not found" error (404), an "unauthorized error" (401) or even a developer generated 500 error. In order to generate such a response from anywhere in your application, you may use the abort helper:

abort(404);

カスタムHTTPエラーページCustom HTTP Error Pages

Laravelを使用すると、さまざまなHTTPステータスコードのカスタムエラーページを簡単に表示できます。たとえば、404 HTTPステータスコードのエラーページをカスタマイズする場合は、resources/views/errors/404.blade.phpビューテンプレートを作成します。このビューは、アプリケーションが生成するすべての404エラーでレンダされます。このディレクトリ内のビューには、対応するHTTPステータスコードと一致する名前を付ける必要があります。abort関数によって生成されたSymfony\Component\HttpKernel\Exception\HttpExceptionインスタンスは$exception変数としてビューに渡されます。Laravel makes it easy to display custom error pages for various HTTP status codes. For example, if you wish to customize the error page for 404 HTTP status codes, create a resources/views/errors/404.blade.php view template. This view will be rendered on all 404 errors generated by your application. The views within this directory should be named to match the HTTP status code they correspond to. The Symfony\Component\HttpKernel\Exception\HttpException instance raised by the abort function will be passed to the view as an $exception variable:

<h2>{{ $exception->getMessage() }}</h2>

vendor:publish Artisanコマンドを使用して、Laravelのデフォルトのエラーページテンプレートをリソース公開できます。テンプレートをリソース公開したら、好みに合わせてカスタマイズしてください。You may publish Laravel's default error page templates using the vendor:publish Artisan command. Once the templates have been published, you may customize them to your liking:

php artisan vendor:publish --tag=laravel-errors

HTTPエラーページのフォールバックFallback HTTP Error Pages

一連のHTTPステータスコードに対応する「フォールバック」エラーページを定義することもできます。このページは、発生した特定のHTTPステータスコードに対応するページが存在しない場合にレンダされます。これには、アプリケーションのresources/views/errorsディレクトリに、4xx.blade.phpテンプレートと5xx.blade.phpテンプレートを定義します。You may also define a "fallback" error page for a given series of HTTP status codes. This page will be rendered if there is not a corresponding page for the specific HTTP status code that occurred. To accomplish this, define a 4xx.blade.php template and a 5xx.blade.php template in your application's resources/views/errors directory.