Download the PHP package phpdot/error-handler without Composer

phpdot/error-handler

A modern error handler for PHP: an HTML debug page in development, clean pages in production, RFC 9457 (application/problem+json) responses for JSON clients, and a PSR-15 middleware for framework pipelines. Renderers, solution providers, and context providers are all pluggable, so the same handler adapts from a one-line global setup to a fully wired request pipeline.

Table of Contents

• Requirements
• Installation
• Usage
• Architecture
• Testing
• License

Requirements

The package depends on PSR interfaces and the phpdot observability contracts — bring any PSR-7/PSR-17 implementation (for example phpdot/http) and a tracer. Handled exceptions are logged through TracerInterface at the status-mapped level and mark the active span error; there is no PSR-3 surface.

Installation

Usage

Global handler

One line registers set_exception_handler, set_error_handler, and a shutdown handler. Uncaught exceptions render a debug page, PHP warnings and notices become exceptions, and fatal errors are caught on shutdown:

Switch to production for clean pages that expose no internals:

PSR-15 middleware

Wrap the whole application pipeline. The middleware catches any Throwable, renders it via the ExceptionHandler, and returns a PSR-7 response with the correct status code and a Content-Type of application/problem+json or text/html depending on the request:

The exception handler directly

ExceptionHandler is the core. Call handle() to turn a throwable into a rendered string, choosing the renderer from the environment and the request's Accept header:

Status codes are derived from the exception: a getStatusCode() method is honoured, and InvalidArgumentException, DomainException, and the rest map to sensible 4xx/5xx codes.

Solution providers

A solution provider suggests a fix for a known error. Solutions appear on the debug page and in the JSON solutions array. A provider that throws is caught silently — collection never crashes the handler:

Context providers

A context provider adds a named tab of data to the debug page. Like solution providers, a throwing provider is caught silently:

Environment variables collected for the debug page are filtered: any key matching a sensitive name (password, secret, token, key, and similar) is masked. Extend the list with setSensitiveKeys().

Architecture

A throwable enters through the global handler or the PSR-15 middleware. ExceptionHandler assembles an ErrorContext — parsed stack trace, filtered environment, provider tabs, and suggested solutions — then hands it to the renderer chosen for the environment and request.

Renderers implement RendererInterface, so a custom renderer is a drop-in replacement. The two HTML renderers load a plain PHP template from templates/; point their constructor at a different path to fully restyle the page.

Testing

The package is standalone-testable:

License

MIT.

This repository is a read-only mirror, generated by CI from phpdot/monorepo. Pull requests and issues belong in the monorepo.