Download the PHP package iviphp/debug without Composer

Ivi Debug

Structured debugging, exception collection and development renderers for the IviPHP ecosystem.

iviphp/debug provides a framework-independent debugging foundation for collecting application messages, exceptions and custom diagnostic information.

It can render the collected information as HTML or JSON and register PHP error, exception and shutdown handlers.

Requirements

• PHP 8.2 or later
• iviphp/contracts
• iviphp/http
• iviphp/support

Installation

Features

• Structured debug messages
• Exception and throwable collection
• Safe stack trace normalization
• Automatic sensitive-data redaction
• Custom debug collectors
• PHP error handler registration
• Uncaught exception handling
• Fatal shutdown error capture
• HTML debug pages
• JSON debug responses
• Configurable collection limits
• Framework-independent architecture
• Safe diagnostic exceptions

Core concepts

Debug manager

DebugManager coordinates:

• collector registration;
• structured messages;
• exception capture;
• collector execution;
• HTML rendering;
• JSON rendering;
• collector reset operations.

Debug API

Debug is the public application-facing wrapper around DebugManager.

Collector

A collector stores or generates one category of diagnostic information.

The package includes:

• MessageCollector;
• ExceptionCollector.

Applications may register their own collectors by implementing DebugCollectorInterface.

Handler

DebugHandler connects the debugging system to PHP's native error, exception and shutdown handling functions.

Renderer

The package includes two renderers:

• HtmlDebugRenderer;
• JsonDebugRenderer.

Creating the debug service

The manager automatically registers a message collector and an exception collector.

Adding debug messages

Add contextual information:

The context must use string keys.

Message levels

The following levels are supported:

A custom level may be passed through message(), but it must be one of the supported levels.

Message categories

Categories can group related messages.

Retrieve messages by category:

Retrieve uncategorized messages:

Retrieving messages

Retrieve messages by level:

Determine whether the collector is empty:

Reset collected messages:

Sensitive context values

The message collector automatically redacts common sensitive keys.

Examples include:

Example:

The collected context contains:

Applications should still avoid sending secrets to the debugging system.

Configuring the message collector

When the configured limit is exceeded, the oldest messages are removed.

Capturing exceptions

Add safe contextual information:

Exception context values must be scalar or null.

Sensitive context keys are automatically redacted.

Exception information

The exception collector records:

• exception class;
• message;
• code;
• file;
• line;
• error severity when applicable;
• normalized stack trace;
• previous exception chain;
• safe context;
• collection timestamp.

Stack trace arguments are intentionally excluded.

Object properties and runtime resources are also excluded.

Retrieving exceptions

Retrieve exceptions by class:

Retrieve PHP errors by severity:

Reset collected exceptions:

Configuring the exception collector

Set includeTrace to false when stack traces should not be collected.

Collecting all debug information

The result is indexed by collector name.

By default, one failing collector does not stop other collectors.

The failed collector produces a safe error entry.

Enable strict collection when failures must be thrown:

Rendering HTML

Render collected information with an exception:

The HTML renderer generates a complete standalone development page containing:

• exception details;
• source location;
• stack trace;
• previous exception information;
• collected debug data.

The output escapes HTML values before rendering.

Rendering JSON

Render an exception as JSON:

Example structure:

Selecting a renderer dynamically

Unsupported formats throw DebugException.

Renderer content types

Returns:

Returns:

Configuring the HTML renderer

Long strings are truncated before rendering.

Deeply nested values are replaced with:

Configuring the JSON renderer

Disable formatted JSON:

Disable exception traces:

Replacing renderers

Retrieve the configured renderers:

Registering PHP handlers

Create and register the default handler:

This registers:

• an exception handler;
• an error handler;
• a shutdown handler for fatal errors.

Check whether the handler is active:

Restore the previous PHP handlers:

Creating a handler without registering it

This is useful when the application controls exactly when handler registration occurs.

Error conversion

By default, supported PHP runtime errors are converted into ErrorException.

Disable conversion and collect errors directly:

When conversion is disabled, handled errors are captured by the exception collector.

Error reporting rules

The handler respects the current error_reporting() mask by default.

To process errors even when excluded from the current mask:

Suppressed errors should generally remain ignored in production applications.

Selecting handled error types

Use E_ALL to support all PHP error types:

Fatal shutdown errors

Fatal shutdown error capture is enabled by default.

Disable it when another system handles shutdown failures:

The handler may capture errors such as:

• E_ERROR;
• E_PARSE;
• E_CORE_ERROR;
• E_COMPILE_ERROR;
• E_USER_ERROR;
• E_RECOVERABLE_ERROR.

Custom exception reporter

A reporter runs after an uncaught exception has been captured.

A JSON reporter may be used for API applications:

Previous exception handlers

The previous exception handler is not called by default.

Enable propagation:

The exception is collected before the previous handler is called.

Custom collectors

Create a collector by implementing DebugCollectorInterface.

Register the collector:

Its output becomes available through:

Collector management

Determine whether a collector exists:

Return all collectors:

Return collector names:

Replace a collector:

Remove a custom collector:

The primary message and exception collectors cannot be removed.

Collection statistics

Return the total number of entries stored by all collectors:

Determine whether all collectors are empty:

Resetting collectors

Reset every registered collector:

By default, reset failures from individual collectors are ignored.

Use strict mode to throw failures:

Exceptions

Debugging-system failures are represented by:

Examples include:

• duplicate collector registration;
• missing collectors;
• invalid collector names;
• invalid collector output;
• handler registration failures;
• handler unregistration failures;
• unsupported renderers;
• JSON encoding failures;
• rendering failures;
• invalid configuration.

Diagnostic context intentionally excludes collected payload contents and sensitive application values.

Development environment example

API environment example

Production usage

Detailed debug output should not be exposed publicly in production.

Production applications should:

• disable browser-facing stack traces;
• avoid returning filesystem paths;
• log exceptions through a protected logging service;
• send generic error responses to clients;
• protect debug routes with authorization;
• redact application-specific secrets;
• restrict access to collected diagnostic data.

The package limits and normalizes diagnostic values, but application-specific confidential data must still be handled carefully.

Design principles

iviphp/debug follows these principles:

• framework-independent collection;
• explicit collector contracts;
• structured debug information;
• safe normalization;
• sensitive-key redaction;
• no stack trace arguments;
• no object-property inspection;
• configurable collection limits;
• separate HTML and JSON renderers;
• compatibility with web, API and CLI applications.

License

Ivi Debug is open-source software released under the MIT License.

Maintainer

Maintained by Gaspard Kirira and Softadastra.