HTTP Exceptions

This document covers HTTP-specific exceptions in the hypervel/http package. These exceptions handle errors related to HTTP request validation and configuration issues. For file upload-related exceptions, see File Upload Exceptions.

Purpose and Scope

The HTTP exceptions in this package provide specialized error handling for:

• Request size validation failures
• Invalid configuration options
• HTTP protocol-level errors with appropriate status codes

These exceptions integrate with the middleware pipeline to enforce request constraints and provide meaningful error responses to clients.

Exception Hierarchy

The package defines two primary HTTP exception types that serve different purposes in the request processing lifecycle:

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

Exception Types

PostTooLargeException

The PostTooLargeException represents HTTP 413 Payload Too Large errors when request content exceeds configured limits.

Property	Value
Namespace	Hypervel\Http\Exceptions
Extends	Hypervel\HttpMessage\Exceptions\HttpException
HTTP Status	413 (Payload Too Large)
Usage Context	Request size validation

Class Structure

The exception constructor automatically sets the HTTP status code to 413 while allowing customization of the error message, previous exception, headers, and error code:

src/Exceptions/PostTooLargeException.php15-18

Parameters:

• $message - Custom error message (default: empty string)
• $previous - Previous exception for exception chaining (optional)
• $headers - Additional HTTP headers for the error response (default: empty array)
• $code - Application-specific error code (default: 0)

Sources: src/Exceptions/PostTooLargeException.php1-19

Integration with ValidatePostSize Middleware

The PostTooLargeException is thrown by the ValidatePostSize middleware when the CONTENT_LENGTH header exceeds the configured post_max_size limit:

The middleware checks the request size at src/Middleware/ValidatePostSize.php19-25:

1. Retrieves the configured post_max_size from PHP ini settings
2. Compares against the CONTENT_LENGTH header value
3. Throws PostTooLargeException with message "The POST data is too large." if exceeded

The getPostMaxSize() method src/Middleware/ValidatePostSize.php31-51 parses PHP's ini format, supporting suffixes:

• K - Kilobytes (× 1024)
• M - Megabytes (× 1048576)
• G - Gigabytes (× 1073741824)
• Numeric values without suffix treated as bytes

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

InvalidOptionException

The InvalidOptionException indicates configuration errors where invalid options are provided to HTTP components.

Property	Value
Namespace	Hypervel\Http\Exceptions
Extends	RuntimeException
HTTP Status	N/A (Not HTTP-specific)
Usage Context	Configuration validation

Class Structure

This is a simple marker exception extending PHP's RuntimeException without additional functionality src/Exceptions/InvalidOptionException.php9-11 The exception relies on the standard exception message to convey configuration problems.

Typical Usage Pattern:

• Thrown when invalid CORS options are provided
• Used for validating middleware configuration
• Indicates programmer error rather than client error

Sources: src/Exceptions/InvalidOptionException.php1-11

Exception Usage Patterns

Request Validation Flow

Error Response Generation

When PostTooLargeException is thrown, the HTTP status code is automatically set to 413, allowing the framework's exception handler to generate an appropriate error response:

Status Code	Exception	Description
413	PostTooLargeException	Request payload exceeds server limits
500	InvalidOptionException	Internal configuration error (typically)

The HttpException base class (from hypervel/http-message) ensures that the status code and any additional headers are properly set on the response.

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

Best Practices

Handling PostTooLargeException

When configuring the ValidatePostSize middleware, ensure your post_max_size ini setting aligns with expected request sizes:

• Configure appropriate limits based on application needs
• Consider separate limits for different routes if necessary
• Monitor for frequent 413 errors indicating misconfiguration

Handling InvalidOptionException

The InvalidOptionException typically indicates a programming error:

• Validate configuration during application initialization
• Use type hints and validation to prevent invalid options
• Document expected option formats and values

Sources: src/Middleware/ValidatePostSize.php1-52 src/Exceptions/InvalidOptionException.php1-11