Whoops Laravel Package

Getting Started

Install via Composer: composer require filp/whoops --dev. Enable in development by swapping PHP's default error handler—typically in public/index.php or a dev-only middleware—using Whoops\Run::pushHandler(new Whoops\Handler\PrettyPageHandler()). The handler renders a beautiful, interactive error page with stack traces, variable inspection, and code preview. Start by adding it to your request lifecycle’s early bootstrap phase—ideally before any output is sent.

Implementation Patterns

• Laravel integration: Use the built-in Whoops service provider (via laravel/framework >= 5.4). It’s automatically enabled in local environment. Customize via config/app.php’s debug flag or config/whoops.php.
• Custom handlers: Chain handlers for layered error handling: e.g., PrettyPageHandler for local dev, JsonResponseHandler for APIs, and PlainTextHandler for CLI.
• Handler customization: Extend Whoops\Handler\Handler to add email alerts, log correlation IDs, or UI tweaks (e.g., setEditor('phpstorm') for one-click file opening).
• Conditional activation: Wrap in environment checks (env('APP_ENV') === 'local') to avoid accidental exposure in production.

Gotchas and Tips

• Headers already sent? The handler fails silently if output has started—ensure no whitespace, BOM, or echo before initialization. Use output buffering or early handler setup.
• Frame filtering: Use PrettyPageHandler::setFramesSkipped() to hide internal framework boilerplate from stack traces, keeping focus on your code.
• Production risk: Never enable full pretty pages in production—leaks sensitive context (paths, DB credentials). Use minimal PlainTextHandler or dedicated error logging services instead.
• IDE integration: Configure $handler->setEditor('vscode|phpstorm|sublime') and paths (e.g., setRootPath('/app'), setUrlCallback(fn($file, $line) => "vscode://file/$file:$line")) for "Open in IDE" links.
• Xdebug conflict: If stack traces appear truncated, ensure xdebug.show_exception_trace=0 and xdebug.collect_vars=1 for full detail—Xdebug sometimes manglesWhoops’ frame info.