Laravel 11.x エラー処理

イントロダクションIntroduction

新しいLaravelプロジェクトを開始すると、エラーと例外処理はあらかじめ設定済みです。しかし、いつでも、アプリケーションのbootstrap/app.phpのwithExceptionsメソッドを使用して、例外をどのように報告し、アプリケーションによってレンダするかを管理できます。When you start a new Laravel project, error and exception handling is already configured for you; however, at any point, you may use the withExceptions method in your application's bootstrap/app.php to manage how exceptions are reported and rendered by your application.

withExceptionsクロージャへ渡される$exceptionsオブジェクトはIlluminate\Foundation\Configuration\Exceptionsインスタンスで、アプリケーションの例外処理を管理します。このドキュメントを通して、このオブジェクトを深く掘り下げていきましょう。The $exceptions object provided to the withExceptions closure is an instance of Illuminate\Foundation\Configuration\Exceptions and is responsible for managing exception handling in your application. We'll dive deeper into this object 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.

例外処理Handling Exceptions

例外のレポートReporting Exceptions

Laravelでは、例外レポートを使用して、例外をログに記録したり、外部サービスのSentry、Flareへ送信したりします。例外はデフォルトで、ログ設定に基づき、ログへ記録します。しかし、例外をどのようにログに記録するかは自由です。In Laravel, exception reporting is used to log exceptions or send them to an external service Sentry[https://github.com/getsentry/sentry-laravel] or Flare[https://flareapp.io]. By default, exceptions will be logged based on your logging[/docs/{{version}}/logging] configuration. However, you are free to log exceptions however you wish.

異なるタイプの例外を別々の方法で報告する必要がある場合、アプリケーションのbootstrap/app.phpでreport例外メソッドを使用して、特定タイプの例外を報告する必要があるときに実行するクロージャを登録できます。Laravelは、クロージャのタイプヒントを調べ、クロージャが報告する例外のタイプを決定します。If you need to report different types of exceptions in different ways, you may use the report exception method in your application's bootstrap/app.php to register a closure that should be executed when an exception of a given type needs to be reported. Laravel will determine what type of exception the closure reports by examining the type-hint of the closure:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(function (InvalidOrderException $e) {
        // ...
    });
})

reportメソッドを使用してカスタム例外報告コールバックを登録すると、Laravelはアプリケーションのデフォルトのログ設定を使用して例外をログに記録します。デフォルトのログスタックへ例外が伝わるのを停止したい場合は、報告コールバックを定義するときにstopメソッドを使用するか、コールバックからfalseを返します：When you register a custom exception reporting callback using the report 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:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(function (InvalidOrderException $e) {
        // ...
    })->stop();

    $exceptions->report(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をコンテキストデータとしてすべての例外のログメッセージへ追加します。アプリケーションのbootstrap/app.phpファイルの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 using the context exception method in your application's bootstrap/app.php file. This information will be included in every exception's log message written by your application:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->context(fn () => [
        '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 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<string, mixed>
     */
    public function context(): array
    {
        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 without rendering an error page to the user:

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

        return false;
    }
}

レポート済み例外の重複Deduplicating Reported Exceptions

アプリケーション全体でreport関数を使用している場合、同じ例外を複数回報告することがあり、ログに重複したエントリが作成されることがあります。If you are using the report function throughout your application, you may occasionally report the same exception multiple times, creating duplicate entries in your logs.

例外で単一インスタンスが一度だけ報告されることを保証したい場合、アプリケーションのbootstrap/app.phpファイルでdontReportDuplicates例外メソッドを呼び出してください。If you would like to ensure that a single instance of an exception is only ever reported once, you may invoke the dontReportDuplicates exception method in your application's bootstrap/app.php file:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->dontReportDuplicates();
})

これで、同じ例外インスタンスでreportヘルパが呼び出された場合、最初に呼び出されたものだけが報告されるようになります。Now, when the report helper is called with the same instance of an exception, only the first call will be reported:

$original = new RuntimeException('Whoops!');

report($original); // レポートされる

try {
    throw $original;
} catch (Throwable $caught) {
    report($caught); // 無視される
}

report($original); // 無視される
report($caught); // 無視される

例外のログレベル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.

上記のように、reportメソッドを使用してカスタム例外報告コールバックを登録した場合でも、Laravelはアプリケーションのデフォルトのログ設定を使用して例外をログに記録します。しかし、ログレベルはメッセージがログに記録されるチャンネルに影響を与えることがあるので、特定の例外をログに記録するログレベルを設定したい場合もあるでしょう。As noted above, even when you register a custom exception reporting callback using the report 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.

これを行うには、アプリケーションのbootstrap/app.phpファイルで、level例外メソッドを使用します。このメソッドは最初の引数として例外タイプを取り、２番目の引数にログレベルを取ります：To accomplish this, you may use the level exception method in your application's bootstrap/app.php file. This method receives the exception type as its first argument and the log level as its second argument:

use PDOException;
use Psr\Log\LogLevel;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->level(PDOException::class, LogLevel::CRITICAL);
})

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

アプリケーションを構築するとき、報告したくないタイプの例外があるでしょう。これらの例外を無視するためには、アプリケーションのbootstrap/app.phpファイルでdontReport例外メソッドを使ってください。このメソッドへ指定したクラスは、報告しません。しかしながら、それらのクラスが、カスタムレンダロジックを持っている可能性はあります。When building your application, there will be some types of exceptions you never want to report. To ignore these exceptions, you may use the dontReport exception method in your application's bootstrap/app.php file. Any class provided to this method will never be reported; however, they may still have custom rendering logic:

use App\Exceptions\InvalidOrderException;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->dontReport([
        InvalidOrderException::class,
    ]);
})

別の方法として、単純に例外クラスをIlluminate\Contracts\Debug\ShouldntReportインターフェイスで「マーク」することもできます。例外がこのインターフェイスでマークされると、Laravelの例外ハンドラでは報告しません。Alternatively, you may simply "mark" an exception class with the Illuminate\Contracts\Debug\ShouldntReport interface. When an exception is marked with this interface, it will never be reported by Laravel's exception handler:

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Contracts\Debug\ShouldntReport;

class PodcastProcessingException extends Exception implements ShouldntReport
{
    //
}

Laravelは内部的に、あらかじめいくつかのタイプのエラーを無視しています。例えば、404 HTTPエラーや無効なCSRFトークンによって生成された419 HTTPレスポンスから生じる例外などです。Laravelが指定しているタイプの例外を無視しないように指示したい場合は、アプリケーションのbootstrap/app.phpファイルで、stopIgnoring例外メソッドを使用してください。Internally, Laravel already ignores some types of errors for you, such as exceptions resulting from 404 HTTP errors or 419 HTTP responses generated by invalid CSRF tokens. If you would like to instruct Laravel to stop ignoring a given type of exception, you may use the stopIgnoring exception method in your application's bootstrap/app.php file:

use Symfony\Component\HttpKernel\Exception\HttpException;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->stopIgnoring(HttpException::class);
})

例外のレンダRendering Exceptions

Laravelの例外ハンドラはデフォルトで、例外をHTTPレスポンスへ変換します。しかし、特定タイプの例外のためにカスタムレンダクロージャを自由に登録することもできます。アプリケーションのboostrap/app.phpファイルで、render例外メソッドを使うことで、これを実現できます。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 by using the render exception method in your application's bootstrap/app.php file.

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

use App\Exceptions\InvalidOrderException;
use Illuminate\Http\Request;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (InvalidOrderException $e, Request $request) {
        return response()->view('errors.invalid-order', status: 500);
    });
})

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

use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => 'Record not found.'
            ], 404);
        }
    });
})

例外をJSONでレンダするRendering Exceptions as JSON

例外をレンダするとき、LaravelはリクエストのAcceptヘッダに基づいて、例外をHTMLレスポンスとしてレンダするか、JSONレスポンスとしてレンダするかを自動的に判断します。Laravelが例外レスポンスをHTMLとJSONのどちらでレンダするかを決定する方法をカスタマイズしたい場合は、shouldRenderJsonWhenメソッドを利用します。When rendering an exception, Laravel will automatically determine if the exception should be rendered as an HTML or JSON response based on the Accept header of the request. If you would like to customize how Laravel determines whether to render HTML or JSON exception responses, you may utilize the shouldRenderJsonWhen method:

use Illuminate\Http\Request;
use Throwable;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->shouldRenderJsonWhen(function (Request $request, Throwable $e) {
        if ($request->is('admin/*')) {
            return true;
        }

        return $request->expectsJson();
    });
})

例外レスポンスのカスタマイズCustomizing the Exception Response

まれに、Laravelの例外ハンドラがレンダするHTTPレスポンス全体をカスタマイズする必要があるかもしれません。これを行うには、respondメソッドを使用してレスポンスのカスタマイズクロージャを登録します。Rarely, you may need to customize the entire HTTP response rendered by Laravel's exception handler. To accomplish this, you may register a response customization closure using the respond method:

use Symfony\Component\HttpFoundation\Response;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->respond(function (Response $response) {
        if ($response->getStatusCode() === 419) {
            return back()->with([
                'message' => 'The page expired, please try again.',
            ]);
        }

        return $response;
    });
})

Reportable／Renderable例外Reportable and Renderable Exceptions

アプリケーションのbootstrap/app.phpファイルでカスタムレポートとレンダ動作を定義する代わりに、アプリケーションの例外に直接、reportとrenderメソッドを定義できます。これらのメソッドが存在するとき、フレームワークは自動的に呼び出します。Instead of defining custom reporting and rendering behavior in your application's bootstrap/app.php file, you may define report and render methods directly on your application's exceptions. When these methods exist, they will automatically be called by the framework:

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class InvalidOrderException extends Exception
{
    /**
     * 例外をレポート
     */
    public function report(): void
    {
        // ...
    }

    /**
     * 例外をHTTPレスポンスへレンダ
     */
    public function render(Request $request): Response
    {
        return response(/* ... */);
    }
}

LaravelやSymfonyの組み込み済み例外など、既存のレンダ可能（Renderable）な例外を拡張している場合は、例外の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:

/**
 * 例外をHTTPレスポンスへレンダする
 */
public function render(Request $request): Response|bool
{
    if (/** この例外をレポートする必要があるかを判断… */) {

        return response(/* ... */);
    }

    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:

/**
 * 例外を報告
 */
public function report(): bool
{
    if (/** この例外をレポートする必要があるかを判断… */) {

        // ...

        return true;
    }

    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].

例外レポートの限定Throttling Reported Exceptions

アプリケーションが非常に多くの例外を報告する場合、実際にログに記録されたり、アプリケーションの外部エラー追跡サービスに送信されたりする例外の数を絞り込みたくなるでしょう。If your application reports a very large number of exceptions, you may want to throttle how many exceptions are actually logged or sent to your application's external error tracking service.

例外のランダムサンプルレートを取るには、アプリケーションのbootstrap/app.phpファイルで、throttle例外メソッドを使ってください。throttleメソッドはLotteryインスタンスを返すクロージャを引数に取ります。To take a random sample rate of exceptions, you may use the throttle exception method in your application's bootstrap/app.php file. The throttle method receives a closure that should return a Lottery instance:

use Illuminate\Support\Lottery;
use Throwable;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->throttle(function (Throwable $e) {
        return Lottery::odds(1, 1000);
    });
})

また、例外の種類に基づいた条件付きでサンプリングすることも可能です。特定の例外クラスのインスタンスのみをサンプリングしたい場合は、そのクラスのLotteryインスタンスのみを返しますIt is also possible to conditionally sample based on the exception type. If you would like to only sample instances of a specific exception class, you may return a Lottery instance only for that class:

use App\Exceptions\ApiMonitoringException;
use Illuminate\Support\Lottery;
use Throwable;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->throttle(function (Throwable $e) {
        if ($e instanceof ApiMonitoringException) {
            return Lottery::odds(1, 1000);
        }
    });
})

また、Lotteryの代わりにLimitインスタンスを返せば、ログに記録する例外や外部のエラー追跡サービスに送信する例外を制限できます。これは、アプリケーションで使用しているサードパーティのサービスがダウンした場合などで、突然例外がログに殺到するのを防ぎたい場合に便利です。You may also rate limit exceptions logged or sent to an external error tracking service by returning a Limit instance instead of a Lottery. This is useful if you want to protect against sudden bursts of exceptions flooding your logs, for example, when a third-party service used by your application is down:

use Illuminate\Broadcasting\BroadcastException;
use Illuminate\Cache\RateLimiting\Limit;
use Throwable;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->throttle(function (Throwable $e) {
        if ($e instanceof BroadcastException) {
            return Limit::perMinute(300);
        }
    });
})

リミットは例外のクラスをレートリミットキーに、デフォルトで使用します。これをカスタマイズするには、Limitのbyメソッドを使用して独自キーを指定します。By default, limits will use the exception's class as the rate limit key. You can customize this by specifying your own key using the by method on the Limit:

use Illuminate\Broadcasting\BroadcastException;
use Illuminate\Cache\RateLimiting\Limit;
use Throwable;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->throttle(function (Throwable $e) {
        if ($e instanceof BroadcastException) {
            return Limit::perMinute(300)->by($e->getMessage());
        }
    });
})

もちろん、異なる例外に対してLotteryとLimitのインスタンスを混ぜて返すこともできます。Of course, you may return a mixture of Lottery and Limit instances for different exceptions:

use App\Exceptions\ApiMonitoringException;
use Illuminate\Broadcasting\BroadcastException;
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Lottery;
use Throwable;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->throttle(function (Throwable $e) {
        return match (true) {
            $e instanceof BroadcastException => Limit::perMinute(300),
            $e instanceof ApiMonitoringException => Lottery::odds(1, 1000),
            default => Limit::none(),
        };
    });
})

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, 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 for 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.

フォールバックエラーページを定義する場合、フォールバックページは404、500、503エラーレスポンスには影響しません。Laravelは内部的に、これらのステータスコード専用のページを持っているためです。これらのステータスコードに対してレンダするページをカスタマイズするには、個別にカスタムエラーページを定義する必要があります。When defining fallback error pages, the fallback pages will not affect 404, 500, and 503 error responses since Laravel has internal, dedicated pages for these status codes. To customize the pages rendered for these status codes, you should define a custom error page for each of them individually.