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

Keyboard Shortcuts (HTML Renderer)

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.