README

Temant Fault

A modern, feature-rich exception handler for PHP.

Fault is an exception handler that catches uncaught exceptions and PHP errors, then renders beautiful, information-rich error pages. It supports HTML, JSON, XML, and plain text output with automatic content negotiation. Part of the Temant Framework.

Features

Interactive HTML error page with syntax-highlighted source code
Stack trace sidebar with frame filtering and keyboard navigation
Tabbed debug panels: Request, Environment, Session, Cookies, Logs, Git, Xdebug
JSON, XML, and plain text renderers for APIs and CLI
Automatic content negotiation via HTTP Accept header
Light/dark theme with localStorage persistence
"Open in editor" links (PHPStorm, VS Code, Sublime, Atom, IntelliJ, NetBeans)
Sensitive data masking (passwords, API keys, tokens)
Exception chain support with full previous-exception rendering
Listener callbacks for logging and external error reporting
Production mode with safe, detail-free error pages
PHPStan level 9 strict typing

Requirements

PHP 8.2 or higher
Extensions: json, mbstring, xmlwriter

Installation

composer require temant-framework/temant-fault

Quick Start

use TemantFramework\Fault\ExceptionHandler;

$handler = new ExceptionHandler();
$handler
    ->setDebug(true)
    ->setApplicationName('My App')
    ->setEditor('vscode')
    ->register();

// That's it. Any uncaught exception will now render a rich error page.

Usage

Basic Setup

use TemantFramework\Fault\ExceptionHandler;

$handler = new ExceptionHandler();
$handler->setDebug(true)->register();

Production Mode

In production, disable debug mode to show a safe, generic error page:

$handler->setDebug(false)->register();

Editor Integration

Configure clickable "Open in editor" links for your IDE:

// Supported: phpstorm, vscode, sublime, atom, idea, netbeans
$handler->setEditor('phpstorm');

Listener Callbacks

Add listeners to log or report exceptions before rendering:

$handler->addListener(function (\Throwable $e): void {
    error_log($e->getMessage());
});

$handler->addListener(function (\Throwable $e): void {
    Sentry::captureException($e);
});

Custom Renderers

Replace any built-in renderer with your own:

use TemantFramework\Fault\ContentType;
use TemantFramework\Fault\Renderer\RendererInterface;
use TemantFramework\Fault\ErrorContext;

$handler->setRenderer(ContentType::Json, new class implements RendererInterface {
    public function render(ErrorContext $context, bool $debug = true): string
    {
        return json_encode(['error' => $context->message]);
    }

    public function contentType(): string
    {
        return 'application/json';
    }
});

Programmatic Rendering

Render exceptions without outputting them:

use TemantFramework\Fault\ContentType;

$html = $handler->render($exception, ContentType::Html);
$json = $handler->render($exception, ContentType::Json);
$xml  = $handler->render($exception, ContentType::Xml);
$text = $handler->render($exception, ContentType::Text);

Default Content Type

Change the fallback format when content negotiation has no match:

use TemantFramework\Fault\ContentType;

$handler->setDefaultContentType(ContentType::Json);

Renderers

Renderer	Content Type	Debug Output	Production Output
`HtmlRenderer`	`text/html`	Interactive debug page	Minimal 500 page
`JsonRenderer`	`application/json`	Full error JSON	`{"error": {"message": "Internal Server Error"}}`
`XmlRenderer`	`application/xml`	Full error XML	`<error><message>Internal Server Error</message></error>`
`PlainTextRenderer`	`text/plain`	Stack trace text	`Internal Server Error`

Keyboard Shortcuts (HTML Renderer)

Key	Action
`j` / `k` or Arrow keys	Navigate stack frames
`/`	Focus frame search
`t`	Toggle light/dark theme
`c`	Copy error to clipboard

Development

# Install dependencies
composer install

# Run tests
composer phpunit

# Run static analysis
composer phpstan

# Run all checks
composer test

# Generate coverage report
composer coverage

Project Structure

fault/
├── src/
│   ├── ContentType.php          # Content type enum with negotiation
│   ├── ErrorContext.php          # Immutable exception data container
│   ├── ExceptionHandler.php     # Central handler (main entry point)
│   └── Renderer/
│       ├── RendererInterface.php # Renderer contract
│       ├── HtmlRenderer.php     # Rich interactive HTML pages
│       ├── JsonRenderer.php     # Structured JSON output
│       ├── XmlRenderer.php      # Well-formed XML documents
│       └── PlainTextRenderer.php# Plain text for CLI/logs
├── tests/
│   └── Unit/                    # PHPUnit test suite
├── examples/
│   └── basic.php                # Usage example
├── build/                       # Cache, coverage (gitignored)
├── composer.json
├── phpunit.xml
├── phpstan.neon                 # PHPStan level 9
└── LICENSE                      # MIT

License

Fault is open-source software licensed under the MIT License.

Part of the Temant Framework.

temant-framework / temant-fault

Maintainers

Package info

Statistics

Security