Exception Handling

The hypervel/http package provides a structured exception hierarchy for handling HTTP-related errors and file upload failures. Exceptions are organized into two primary categories: HTTP protocol exceptions (HTTP status codes) and file upload exceptions (PHP upload error codes).

This page provides an overview of the exception architecture and how exceptions integrate with the request processing pipeline. For detailed documentation:

• HTTP Exceptions: See page 6.1 for PostTooLargeException and other HTTP-related exceptions
• File Upload Exceptions: See page 6.2 for file upload-specific exceptions like FileNotFoundException, IniSizeFileException, etc.

For information about middleware that throws HTTP exceptions, see page 4. For file upload processing, see page 2.4.

Exception Architecture

The package defines two primary exception categories: HTTP exceptions for protocol-level errors and file upload exceptions for file handling failures. These exceptions integrate with the request processing pipeline to provide clear error reporting and appropriate HTTP status codes.

Sources: src/Exceptions/PostTooLargeException.php1-19 src/Exceptions/InvalidOptionException.php1-11 src/UploadedFile.php14-22

HTTP Exceptions Overview

HTTP exceptions represent protocol-level errors with appropriate HTTP status codes. The package provides the following HTTP exception types:

Exception Class	HTTP Status	Purpose	Thrown By
PostTooLargeException	413	Request payload exceeds post_max_size	ValidatePostSize middleware
InvalidOptionException	N/A (RuntimeException)	Invalid configuration or option values	Configuration validation

Key Characteristics:

• PostTooLargeException extends HttpException (from Hypervel\HttpMessage\Exceptions)
• InvalidOptionException extends PHP's standard RuntimeException
• HTTP exceptions are thrown early in the middleware pipeline before application code executes

For detailed documentation of HTTP exceptions including constructor signatures, usage patterns, and integration with middleware, see page 6.1.

Sources: src/Exceptions/PostTooLargeException.php1-19 src/Middleware/ValidatePostSize.php1-52

File Upload Exceptions Overview

The file upload exception system maps PHP's upload error codes to specific exception types. All file upload exceptions extend the base FileException class.

PHP Upload Error Code Mapping:

PHP Constant	Exception Class	Triggered When
UPLOAD_ERR_INI_SIZE	IniSizeFileException	File exceeds upload_max_filesize
UPLOAD_ERR_FORM_SIZE	FormSizeFileException	File exceeds form's MAX_FILE_SIZE
UPLOAD_ERR_PARTIAL	PartialFileException	Upload was interrupted
UPLOAD_ERR_NO_FILE	NoFileException	No file was uploaded
UPLOAD_ERR_CANT_WRITE	CannotWriteFileException	Cannot write file to disk
UPLOAD_ERR_NO_TMP_DIR	NoTmpDirFileException	Missing temporary directory
UPLOAD_ERR_EXTENSION	ExtensionFileException	PHP extension stopped upload

Additional File Exceptions:

• FileNotFoundException: File path does not exist
• FileException: Generic file operation failures (MIME detection, content reading, move operations, etc.)

Key Features:

• Error messages defined in src/UploadedFile.php32-40 include contextual information (filename, size limits)
• Exceptions thrown by UploadedFile::move() method src/UploadedFile.php385-402
• Support for testing via File class with $test flag

For detailed documentation of each exception type including error messages, throw locations, and usage patterns, see page 6.2.

Sources: src/UploadedFile.php14-22 src/UploadedFile.php32-40 src/UploadedFile.php385-402

Exception Integration in Request Pipeline

Exceptions are integrated at multiple points in the request processing pipeline, providing early validation and clear error reporting.

Title: Request Pipeline Exception Points

Pipeline Stages:

1. Request Size Validation (src/Middleware/ValidatePostSize.php17-26): Checks CONTENT_LENGTH header before request body is parsed
2. Route Matching (CoreMiddleware): Validates route existence and HTTP method
3. File Upload Processing (src/UploadedFile.php50-73): Validates file existence during instantiation
4. File Operations (src/UploadedFile.php364-403): Maps PHP upload errors to specific exceptions during move operations

Sources: src/Middleware/ValidatePostSize.php17-26 src/UploadedFile.php50-73 src/UploadedFile.php364-403

Exception Usage Patterns

Middleware Exception Handling

The ValidatePostSize middleware demonstrates early exception throwing in the request pipeline:

The middleware calculates post_max_size by parsing the PHP INI value and converting metric suffixes (K, M, G) to bytes src/Middleware/ValidatePostSize.php31-51

Sources: src/Middleware/ValidatePostSize.php17-26 src/Middleware/ValidatePostSize.php31-51

File Move Exception Resolution

The UploadedFile::move() method uses a switch statement to map error codes to exceptions src/UploadedFile.php385-400:

Error Code	Switch Case Line	Exception Type	Additional Data
UPLOAD_ERR_INI_SIZE	386	IniSizeFileException	Maximum filesize in KiB
UPLOAD_ERR_FORM_SIZE	388	FormSizeFileException	-
UPLOAD_ERR_PARTIAL	390	PartialFileException	-
UPLOAD_ERR_NO_FILE	392	NoFileException	-
UPLOAD_ERR_CANT_WRITE	394	CannotWriteFileException	-
UPLOAD_ERR_NO_TMP_DIR	396	NoTmpDirFileException	-
UPLOAD_ERR_EXTENSION	398	ExtensionFileException	-
Other	402	FileException	Generic error message

Each exception receives its message from getErrorMessage() src/UploadedFile.php493-501 which formats the error template with the client filename and calculated maximum size for UPLOAD_ERR_INI_SIZE.

Sources: src/UploadedFile.php385-402 src/UploadedFile.php493-501

Error Message Generation

The getErrorMessage() method generates contextual error messages:

The method compares post_max_size and upload_max_filesize to determine the effective limit src/UploadedFile.php410-416 using the minimum of the two values or PHP_INT_MAX if either is not set.

Sources: src/UploadedFile.php493-501 src/UploadedFile.php410-416

Testing Exception Handling

The File test class src/Testing/File.php1-116 extends UploadedFile with the $test flag set to true src/Testing/File.php39 This affects validation behavior in isValid() src/UploadedFile.php272-277 which checks the test flag to determine whether to use parent::isValid() (which performs is_uploaded_file() checks) or simply verify the error code equals UPLOAD_ERR_OK.

This allows test files to bypass PHP's upload verification while still exercising exception-throwing code paths.

Sources: src/Testing/File.php27-40 src/UploadedFile.php272-277