Exception Handling and Debugging

This document explains exception handling and debugging infrastructure in Hypervel, including exception reporting and rendering, enhanced variable dumping with source resolution, and compiled view file handling. The framework provides customizable exception pipelines while maintaining coroutine-safe state, and enhances Symfony's VarDumper with intelligent source tracking that resolves compiled view files to their original templates.

For information about HTTP-specific exceptions and status codes, see HTTP Layer. For validation-specific error handling, see page 3.1. For monitoring and observability, see page 10.

---

Overview

Hypervel's exception handling and debugging system consists of three main components:

Component	Purpose	Key Classes
Exception Handler	Reports and renders exceptions into HTTP responses	Handler, ExceptionHandlerContract
Enhanced VarDumper	Provides source-aware variable dumping with editor links	CliDumper, HtmlDumper, ResolvesDumpSource
Command Exception Listener	Renders console command exceptions	FoundationServiceProvider

The system integrates with Hyperf's coroutine Context for thread-safe state management and provides Laravel-compatible APIs for exception customization.

Sources: src/foundation/src/Exceptions/Handler.php47-880 src/foundation/src/Providers/FoundationServiceProvider.php1-202

---

Handler Architecture

The exception handler is implemented in the Handler class, which extends Hyperf's ExceptionHandler and implements the ExceptionHandlerContract interface. It serves as the central point for both reporting exceptions to logs and rendering them into HTTP responses.

Sources: src/foundation/src/Exceptions/Handler.php47-880 src/foundation/src/Exceptions/Contracts/ExceptionHandler.php1-37

The Handler class provides two primary operations:

Method	Purpose	Returns
report(Throwable $e)	Reports/logs the exception using configured reporting strategies	void
render(Request $request, Throwable $e)	Converts the exception into an HTTP response	ResponseInterface
handle(Throwable $throwable, ResponseInterface $response)	Hyperf integration method that calls both report() and render()	ResponseInterface

---

Exception Reporting Pipeline

The reporting pipeline determines whether an exception should be logged and how it should be logged. It executes in the following order:

Sources: src/foundation/src/Exceptions/Handler.php264-315 src/foundation/src/Exceptions/Handler.php317-335

Exception Reporting Configuration

The handler provides several configuration arrays to control reporting behavior:

Property	Type	Purpose
$dontReport	array<class-string>	User-defined exceptions that should not be reported
$internalDontReport	array<class-string>	Framework exceptions that should not be reported
$reportCallbacks	ReportableHandler[]	Custom reporting callbacks registered via reportable()
$contextCallbacks	Closure[]	Callbacks to build additional context for logging
$levels	array<class-string, LogLevel::*>	Custom log levels for specific exception types
$withoutDuplicates	bool	Whether to deduplicate exception reporting in the same coroutine

Sources: src/foundation/src/Exceptions/Handler.php52-134

Internal Don't Report List

The following exception types are never reported by default:

• AuthenticationException - Authentication failures
• AuthorizationException - Authorization/permission failures
• HyperfHttpException - HTTP status exceptions
• HttpResponseException - Exceptions that carry responses
• ModelNotFoundException - Eloquent model not found
• TokenMismatchException - CSRF token mismatches
• ValidationException - Input validation failures

Sources: src/foundation/src/Exceptions/Handler.php110-118

Reporting Customization Methods

Sources: src/foundation/src/Exceptions/Handler.php153-257

Registering Reportable Callbacks

The reportable() method registers callbacks that handle specific exception types with dependency injection support:

src/foundation/src/Exceptions/Handler.php153-162

Setting Custom Log Levels

Different exception types can be logged at different severity levels:

src/foundation/src/Exceptions/Handler.php252-257

Context Building

The handler builds logging context by merging three sources:

1. Exception Context: If the exception has a context() method, its return value is included
2. Custom Context Callbacks: Registered via buildContextUsing()
3. Default Context: Automatically includes the authenticated user ID via Auth::id()

src/foundation/src/Exceptions/Handler.php370-409

Sources: src/foundation/src/Exceptions/Handler.php370-419

---

Exception Rendering Pipeline

The rendering pipeline converts exceptions into HTTP responses, supporting both JSON and HTML formats with content negotiation.

Sources: src/foundation/src/Exceptions/Handler.php426-450

Exception Preparation

Before rendering, certain exceptions are transformed into HTTP exceptions:

Original Exception	Transformed To	Status Code
ModelNotFoundException	NotFoundHttpException	404
AuthorizationException (with status)	HttpException	Custom status
AuthorizationException (no status)	AccessDeniedHttpException	403

src/foundation/src/Exceptions/Handler.php767-780

Sources: src/foundation/src/Exceptions/Handler.php767-780

Response Format Determination

The handler determines whether to return JSON or HTML based on:

1. Custom shouldRenderJsonWhenCallback if registered via shouldRenderJsonWhen()
2. Otherwise, the request's expectsJson() method (checks Accept header and AJAX indicators)

src/foundation/src/Exceptions/Handler.php649-664

Sources: src/foundation/src/Exceptions/Handler.php649-664

Rendering Special Exception Types

Authentication Exceptions

AuthenticationException is rendered as:

• JSON requests: {"message": "..."} with 401 status
• Web requests: Redirect to route('login') or exception's redirectTo() value

src/foundation/src/Exceptions/Handler.php547-552

Validation Exceptions

ValidationException handling depends on request type and session availability:

For Web Requests with Session:

1. Flash validation errors to session under the exception's error bag key (default: 'default')
2. Flash input except fields listed in $dontFlash (passwords, etc.)
3. Redirect to $exception->redirectTo or UrlGenerator::previous()

src/foundation/src/Exceptions/Handler.php567-603

For JSON Requests:

src/foundation/src/Exceptions/Handler.php638-644

Fields Never Flashed:

• current_password
• password
• password_confirmation

Additional fields can be excluded via dontFlash().

src/foundation/src/Exceptions/Handler.php125-228

Sources: src/foundation/src/Exceptions/Handler.php557-644

---

Context-Based State Management

The exception handler uses Hyperf's Context system to store coroutine-local state, ensuring thread-safety in Swoole's coroutine environment.

Sources: src/foundation/src/Exceptions/Handler.php317-542

Duplicate Exception Tracking

When dontReportDuplicates() is enabled, the handler tracks reported exceptions using coroutine context:

src/foundation/src/Exceptions/Handler.php317-335

The tracking storage:

• Key: __errors.reportedExceptions
• Value: Array of exception object references
• Comparison: Uses PHP's in_array() with object identity

This prevents the same exception instance from being reported multiple times within a single request/coroutine context.

src/foundation/src/Exceptions/Handler.php282-284 src/foundation/src/Exceptions/Handler.php348-353

Sources: src/foundation/src/Exceptions/Handler.php317-365 src/foundation/src/Exceptions/Handler.php841-846

After Response Callbacks

The afterResponse() method registers callbacks that modify the exception response before it's returned. These callbacks are stored in coroutine context:

src/foundation/src/Exceptions/Handler.php526-542

Context Storage:

• Key: __errors.handler.afterResponse
• Value: Array of callables
• Execution: During finalizeRenderedResponse() after exception is rendered

Example usage:

src/foundation/src/Exceptions/Handler.php455-471

Sources: src/foundation/src/Exceptions/Handler.php455-542

---

Customization API

The handler provides a fluent API for customizing exception handling behavior:

Exception Mapping

Map one exception type to another using the map() method:

src/foundation/src/Exceptions/Handler.php181-194

Mapped exceptions are transformed during both reporting and rendering.

src/foundation/src/Exceptions/Handler.php266 src/foundation/src/Exceptions/Handler.php428

Sources: src/foundation/src/Exceptions/Handler.php181-194 src/foundation/src/Exceptions/Handler.php476-491

Render Callbacks

Register custom renderers for specific exception types:

src/foundation/src/Exceptions/Handler.php167-176

The handler uses reflection to determine which exception types each callback handles, checking the first closure parameter types.

src/foundation/src/Exceptions/Handler.php498-511

Sources: src/foundation/src/Exceptions/Handler.php167-176 src/foundation/src/Exceptions/Handler.php498-511

Ignore Exceptions

Prevent specific exceptions from being reported:

src/foundation/src/Exceptions/Handler.php209-216

To restore reporting for previously ignored exceptions:

src/foundation/src/Exceptions/Handler.php233-244

Sources: src/foundation/src/Exceptions/Handler.php201-244

Response Finalization

Customize the final response transformation:

src/foundation/src/Exceptions/Handler.php757-762

Sources: src/foundation/src/Exceptions/Handler.php757-762

---

Error View Resolution

For HTTP exceptions rendered as HTML, the handler attempts to resolve custom error views in order:

Sources: src/foundation/src/Exceptions/Handler.php793-808

View Resolution Algorithm

src/foundation/src/Exceptions/Handler.php793-808

1. Try specific view: errors::{statusCode} (e.g., errors::404)
2. Try fallback view: errors::{statusFamily}xx (e.g., errors::4xx)
3. If neither exists, render default HTML error page

The views receive:

• $errors: Empty ViewErrorBag instance
• $exception: The HttpException instance

src/foundation/src/Exceptions/Handler.php731-752

Error View Path Registration

The handler automatically registers the framework's error view paths during construction:

src/foundation/src/Exceptions/Handler.php785-788

This is handled by the RegisterErrorViewPaths bootstrapper.

Sources: src/foundation/src/Exceptions/Handler.php731-808

---

JSON Response Format

When rendering exceptions as JSON, the format varies based on debug mode:

Debug Mode Enabled

Debug Mode Disabled

For HttpException instances in production, the actual exception message is shown instead of "Server Error".

src/foundation/src/Exceptions/Handler.php825-836

Sources: src/foundation/src/Exceptions/Handler.php813-836

---

Integration with HTTP Kernel

The exception handler is invoked by Hyperf's exception handling system during request processing:

Sources: src/foundation/src/Exceptions/Handler.php866-874

The handle() method serves as the Hyperf integration point:

src/foundation/src/Exceptions/Handler.php866-874

This method:

1. Reports the exception via report()
2. Renders the exception via render()
3. Returns the rendered response

The isValid() method always returns true, indicating this handler processes all exceptions.

src/foundation/src/Exceptions/Handler.php876-879

Sources: src/foundation/src/Exceptions/Handler.php866-879

---

Debug Mode Rendering

When app.debug is enabled, the handler provides detailed exception information:

HTML Rendering

The handler uses either:

1. A bound ExceptionRenderer contract implementation (if available)
2. The HtmlErrorRenderer for Symfony-style error pages

src/foundation/src/Exceptions/Handler.php705-726

Exception-to-Response Conversion

For non-HTTP exceptions in debug mode, the handler creates a response with:

• Full exception HTML from the renderer
• Status code 500 (or the exception's status if it's an HttpException)
• Headers from HttpException instances

src/foundation/src/Exceptions/Handler.php669-680 src/foundation/src/Exceptions/Handler.php685-700

Sources: src/foundation/src/Exceptions/Handler.php669-726

---

Summary of Context Keys

The exception handler uses the following Hyperf context keys for coroutine-local state:

Context Key	Type	Purpose
__errors.reportedExceptions	Throwable[]	Tracks reported exceptions for duplicate detection
__errors.handler.afterResponse	callable[]	Stores after-response callbacks

These keys are automatically scoped to the current coroutine and are cleaned up when the coroutine completes.

Sources: src/foundation/src/Exceptions/Handler.php317-542