ErrorHandler

The ErrorHandler acts as the safety net for the application. It captures Exceptions, Fatal Errors, and Parse Errors, converting them into structured responses—whether that's a JSON payload for AJAX requests or a rich, actionable diagnostic UI for the browser.

Error Trapping Flow

The handler automatically detects the request context to determine the appropriate output format.

Rich Diagnostics

Unlike standard PHP error screens, `ErrorHandler` parses PulsePoint-specific exceptions to provide context-aware solutions.

❖ Component Validation

When a component receives invalid props, the ErrorHandler generates a UI showing:

The specific component name.
The invalid property.
Quick Fixes (e.g., "Add public $prop to class").
A list of currently available props.

⚡ Template Compilation

When the template engine fails to parse a file:

Identifies syntax errors in PulsePoint specific tags.
Highlights the specific line in the view file.
Provides suggestions on how to correct the syntax.

Configuration & Output Control

Customizing the Error View

To override the default error layout, create a file at APP_PATH . '/error.php'. If this file exists, the ErrorHandler will render it inside your main layout wrapper instead of the default output.

⚠️ Output Buffering Behavior

When a fatal error occurs, the handler calls ob_end_clean() to wipe any partial HTML generated before the crash. This prevents broken layouts from rendering.

Debugging Tip: If you are trying to debug using echo or var_dump immediately before a crash, you may need to temporarily disable the buffer cleaning in modifyOutputLayoutForError to see your debug output.

Key Methods

static registerHandlers(): void

Registers the set_exception_handler, register_shutdown_function, and set_error_handler. Usually called in bootstrap.php.

static checkFatalError(): void

Manually checks error_get_last(). Useful for catching errors that occur during script shutdown that strictly aren't exceptions.

static formatExceptionForDisplay(Throwable $e): string

Converts a raw Exception object into the formatted HTML string (the "Rich Diagnostics" described above). It determines if the error is a standard PHP exception or a specific PulsePoint framework error.

Manual Usage

While usually handled automatically by the Bootstrap, you can manually invoke the error display logic if creating custom try-catch blocks in your controllers.

<?php
use PP\ErrorHandler;
use PP\PHPX\Exceptions\ComponentValidationException;

try {
    // Some complex logic
    throw new ComponentValidationException("Missing required prop 'id'", 500);
} catch (Throwable $e) {
    // Generate the rich HTML error card
    $html = ErrorHandler::formatExceptionForDisplay($e);
    
    // Output it using the standard layout wrapper
    ErrorHandler::modifyOutputLayoutForError($html);
}
?>