LaravelでWhoopsを使って詳細なエラー画面を表示する方法！ローカル開発環境向け完全ガイド

1. Whoopsとは何か？どんなことができるのか

1. Whoopsとは何か？どんなことができるのか

Whoopsとは、PHPアプリケーション向けのエラーハンドリングライブラリです。ライブラリとは、よく使う機能をまとめて再利用できるようにしたプログラムの部品集のことです。

Laravelのデフォルト（初期設定）のエラー画面は、エラーの種類とメッセージが表示されるシンプルなものです。しかしWhoopsを導入すると、エラーが起きたファイル名・行番号・そのファイルのコード全体・エラーの呼び出し履歴（スタックトレース）・サーバー情報などを色分けして見やすく表示してくれます。

スタックトレースとは、エラーが発生するまでにどのファイルのどの関数が順番に呼び出されたかを一覧にしたものです。料理の手順書でいえば「どの工程でミスをしたか」を追跡できるリストのようなものです。この情報があると、エラーの原因をたどるのがとても簡単になります。

Whoopsはあくまでも開発中（ローカル環境）での利用を想定したツールです。本番環境（実際にユーザーが使う環境）では詳細なエラー情報を表示するとセキュリティ上のリスクになるため、絶対に使わないようにしましょう。

2. WhoopsをComposerでインストールする方法

2. WhoopsをComposerでインストールする方法

WhoopsはComposerというPHPのパッケージ管理ツールを使って簡単にインストールできます。Composerとは、PHPのプロジェクトで必要なライブラリを自動でダウンロードして管理してくれるツールです。

ターミナル（文字を打ち込んでパソコンに命令する画面）でLaravelプロジェクトのフォルダに移動してから、以下のコマンドを実行します。

// 開発環境のみにインストールするコマンド（--dev オプションで本番には含まれない）
composer require filp/whoops --dev

--devオプションをつけることで「開発時だけ使うパッケージ」として登録されます。このオプションをつけるとcomposer.jsonファイルのrequire-devという項目に追加され、本番環境でインストールするときに自動的に除外されます。composer.jsonとは、プロジェクトが使っているライブラリの一覧を管理するファイルです。

インストールが完了するとvendorフォルダの中にWhoopsのファイルが追加されます。vendorフォルダとは、Composerでインストールしたすべてのライブラリが格納される場所です。

3. LaravelとWhoopsの関係を理解しよう

3. LaravelとWhoopsの関係を理解しよう

実はLaravel自体がWhoopsとの連携を標準でサポートしています。Laravelのエラーハンドリング（エラー処理）の中核を担うapp/Exceptions/Handler.phpは、内部でWhoopsを呼び出す準備ができているため、インストールするだけで自動的に適用されることがあります。

ただしWhoopsが有効になる条件があります。.envファイルのAPP_DEBUGがtrueになっていることが必要です。APP_DEBUG=trueのときはLaravelが詳細なエラー情報を表示するモードになり、Whoopsのリッチなエラー画面が使われます。

// .envファイルの設定確認（開発環境の場合）
APP_ENV=local
APP_DEBUG=true   // trueにするとWhoopsのエラー画面が表示される

APP_ENV=localは「このアプリはローカル（自分のパソコン）で動いています」という設定です。APP_DEBUG=trueにすることで詳細なエラー情報が画面に表示されます。本番環境では必ずAPP_DEBUG=falseにして、エラーの詳細をユーザーに見せないようにすることが大切です。

4. Whoopsのエラー画面の見方と活用方法

4. Whoopsのエラー画面の見方と活用方法

Whoopsが有効な状態でエラーが発生すると、ブラウザに色分けされたエラー画面が表示されます。この画面にはいくつかの重要な情報が含まれています。

画面の上部にはエラーの種類とメッセージが大きく表示されます。たとえば「ErrorException: Undefined variable $user」と表示されていれば、「$userという変数が定義されていない」というエラーが起きたことがわかります。

その下にはコードのハイライト表示があります。エラーが発生した行が色つきで強調表示され、その前後のコードも見られます。これにより「どこに問題があるか」をすぐに特定できます。

さらに下にはスタックトレースが一覧表示されます。各項目をクリックすると、その時点のファイルとコードが展開表示されます。エラーの流れを上から順に追っていくことで、根本的な原因を見つけることができます。

画面の右側にはリクエスト情報（アクセスのURL・HTTPメソッドなど）、Cookie（クッキー：ブラウザに保存される小さなデータ）の内容、セッション（ユーザーの状態を一時保存したもの）の内容なども確認できます。これらの情報を組み合わせることで、どんな操作をしたときにエラーが起きたかを詳しく調べることができます。

5. 手動でWhoopsを設定する方法（カスタマイズが必要な場合）

5. 手動でWhoopsを設定する方法（カスタマイズが必要な場合）

通常はインストールとAPP_DEBUG=trueの設定だけで動きますが、Whoopsの動作を細かくカスタマイズしたい場合は、サービスプロバイダーを使って手動で設定することもできます。サービスプロバイダーとはLaravelの起動時に各種機能を登録・初期化するクラスのことです。

以下はapp/Providers/AppServiceProvider.phpにWhoopsを手動で登録する例です。

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Whoops\Run as WhoopsRun;
use Whoops\Handler\PrettyPageHandler;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // ローカル環境のときだけWhoopsを登録する
        if ($this->app->isLocal()) {
            $whoops = new WhoopsRun;
            $whoops->pushHandler(new PrettyPageHandler);
            $whoops->register();
        }
    }
}

$this->app->isLocal()は「現在の環境がローカル（開発環境）かどうか」を確認するメソッドです。trueのときだけWhoopsを有効にすることで、本番環境で誤って有効になるリスクを防げます。PrettyPageHandlerがWhoopsのきれいなエラー画面を生成するクラスです。

6. Whoopsのエラー画面からエディタを開く便利な設定

6. Whoopsのエラー画面からエディタを開く便利な設定

Whoopsには、エラー画面のファイル名・行番号をクリックすると直接コードエディタ（プログラムを書くソフト）でそのファイルを開くリンク機能があります。これを使うと、エラー箇所のファイルを自分で探して開く手間が省けて作業がとてもスムーズになります。

使用しているエディタの設定をPrettyPageHandlerに渡すことで有効になります。VS Code（Visual Studio Code）を使っている場合は以下のように設定します。

<?php

use Whoops\Handler\PrettyPageHandler;

$handler = new PrettyPageHandler;

// VS Codeでファイルを開けるようにエディタを指定する
$handler->setEditor('vscode');

// 他のエディタの指定例
// $handler->setEditor('phpstorm');   // PhpStorm
// $handler->setEditor('sublime');    // Sublime Text
// $handler->setEditor('atom');       // Atom

setEditor()メソッドにエディタ名を渡すだけで設定できます。設定後はWhoopsのエラー画面に表示されるファイル名がリンクになり、クリックするとそのエディタで該当ファイルが自動的に開きます。特にエラーが深いファイルの中で起きている場合に、この機能があると作業効率が大幅にアップします。

7. 本番環境でWhoopsを無効にする重要性と確認方法

7. 本番環境でWhoopsを無効にする重要性と確認方法

Whoopsは開発を助けてくれる非常に便利なツールですが、本番環境で有効になっていると重大なセキュリティリスクになります。エラー画面にはファイルのパス（場所）・データベースの設定情報・変数の中身など、悪意のある第三者に知られてはいけない情報が含まれる可能性があるからです。

本番環境では必ず以下の設定になっていることを確認しましょう。

// 本番環境の.envファイル設定（必ずこうする）
APP_ENV=production
APP_DEBUG=false   // falseにするとWhoopsは無効になる

APP_DEBUG=falseにすることで、エラーが起きても詳細情報は表示されず、シンプルなエラーページだけが表示されます。APP_ENV=productionは「本番環境で動いています」という宣言です。Laravelはこの設定を見て動作を切り替えるため、デプロイ（サーバーへの公開）のたびに.envファイルの内容を確認する習慣をつけることが大切です。

またcomposer install --no-devコマンドを使って本番環境にインストールすると、--devオプションつきでインストールしたWhoopsなどのパッケージは含まれません。これにより開発ツールが本番サーバーに混入するリスクも防げます。本番と開発でパッケージを正しく分けて管理することが、安全なLaravelアプリ開発の基本姿勢といえます。