Request Validation Middleware

Purpose and Scope

This document describes the request validation middleware component, specifically the ValidatePostSize middleware that validates incoming POST request sizes against PHP's configured post_max_size limit. This middleware operates early in the request processing pipeline to reject requests that exceed the server's configured limits before resource-intensive processing occurs.

For general request input validation using validator rules, see section 2.6. For other security middleware, see CORS Middleware. For the broader middleware pipeline architecture, see Core Middleware & Request Lifecycle.

Overview

The request validation middleware system consists of two primary components:

Component	File Path	Purpose
ValidatePostSize	src/Middleware/ValidatePostSize.php	PSR-15 middleware that validates Content-Length against post_max_size
PostTooLargeException	src/Exceptions/PostTooLargeException.php	HTTP 413 exception thrown when POST data exceeds limits

The ValidatePostSize class implements PSR-15 MiddlewareInterface and checks if the CONTENT_LENGTH header exceeds PHP's post_max_size configuration.

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

Middleware Architecture

</old_str>

<old_str>

Class Structure

The ValidatePostSize class structure:

Diagram: ValidatePostSize Class Hierarchy

Class	Properties	Methods
ValidatePostSize	postMaxSize: ?int	process(), getPostMaxSize()
PostTooLargeException	(inherited)	__construct()

Sources: src/Middleware/ValidatePostSize.php13-52 src/Exceptions/PostTooLargeException.php10-19 </old_str> <new_str> Diagram: ValidatePostSize::process() Method Flow

The middleware executes early in the request pipeline, before CoreMiddleware dispatches to controllers.

Sources: src/Middleware/ValidatePostSize.php17-26

Diagram: ValidatePostSize Request Processing Flow

The middleware sits in the early stages of the request pipeline, as shown in the high-level architecture diagrams. It performs validation before the request reaches CoreMiddleware or any controller logic.

Sources: src/Middleware/ValidatePostSize.php17-26

ValidatePostSize Implementation

The process() method src/Middleware/ValidatePostSize.php17-26 executes these steps:

1. Calls getPostMaxSize() to retrieve the byte limit
2. Extracts CONTENT_LENGTH via $request->getHeaderLine('CONTENT_LENGTH')
3. Compares: if $max > 0 && (int)$contentLength > $max, throws PostTooLargeException
4. Otherwise, delegates to $handler->handle($request)

The validation condition at src/Middleware/ValidatePostSize.php21:

• Requires $max > 0 (zero or negative disables validation)
• Compares (int) $request->getHeaderLine('CONTENT_LENGTH') against $max
• Throws PostTooLargeException with message "The POST data is too large."

Validation Logic

The process method src/Middleware/ValidatePostSize.php17-26 performs the following steps:

1. Retrieve Maximum Size: Calls getPostMaxSize() to determine the configured limit
2. Check Content-Length: Extracts the CONTENT_LENGTH header from the request
3. Compare Values: If max > 0 and content length > max, validation fails
4. Throw Exception: Creates a PostTooLargeException with the message "The POST data is too large."
5. Continue Processing: If validation passes, delegates to the next handler

The validation occurs at src/Middleware/ValidatePostSize.php21-23:

• Checks if $max > 0 (zero or negative values disable the check)
• Compares (int) $request->getHeaderLine('CONTENT_LENGTH') against the max
• Throws PostTooLargeException on failure

Sources: src/Middleware/ValidatePostSize.php17-26

Post Max Size Calculation

The getPostMaxSize() method src/Middleware/ValidatePostSize.php31-51 converts PHP's post_max_size INI directive from string notation to bytes:

Diagram: Post Max Size Parsing Algorithm

The method implements caching at src/Middleware/ValidatePostSize.php33-35 to avoid repeated INI parsing. The conversion logic at src/Middleware/ValidatePostSize.php41-50 supports standard PHP shorthand notation:

Suffix	Multiplier	Calculation	Example
K or k	1024	value × 1024	"8K" = 8192 bytes
M or m	1048576	value × 1024²	"8M" = 8,388,608 bytes
G or g	1073741824	value × 1024³	"2G" = 2,147,483,648 bytes
(none)	1	value as-is	"1024" = 1024 bytes

A match expression at src/Middleware/ValidatePostSize.php45-50 determines the multiplier based on strtoupper(substr($postMaxSize, -1)).

Sources: src/Middleware/ValidatePostSize.php31-51

PostTooLargeException

Exception Structure

The PostTooLargeException class extends Hypervel\HttpMessage\Exceptions\HttpException and represents an HTTP 413 Payload Too Large error:

Diagram: Exception Inheritance Hierarchy

Sources: src/Exceptions/PostTooLargeException.php10-19

Constructor Parameters

The __construct() method at src/Exceptions/PostTooLargeException.php15-18:

Parameter	Type	Default	Description
$message	string	''	Error message
$previous	?Throwable	null	Previous exception
$headers	array	[]	Additional HTTP headers
$code	int	0	Internal error code

The constructor passes 413 as the first argument to parent::__construct() at src/Exceptions/PostTooLargeException.php17 setting the HTTP status to 413 Payload Too Large.

Sources: src/Exceptions/PostTooLargeException.php15-18

Integration with Request Pipeline

The ValidatePostSize middleware integrates into the middleware stack defined by the application configuration. Its position in the pipeline is critical:

Diagram: Request Processing Sequence with Size Validation

The middleware typically executes after HandleCors but before CoreMiddleware. This placement:

1. Rejects invalid requests before expensive processing
2. Prevents memory exhaustion from oversized payloads
3. Provides immediate feedback via HTTP 413 response

Sources: src/Middleware/ValidatePostSize.php17-26

Configuration Considerations

PHP INI Settings

The middleware reads PHP's post_max_size via ini_get('post_max_size') at src/Middleware/ValidatePostSize.php37 This directive can be configured in:

• php.ini
• .htaccess (Apache with mod_php)
• ini_set() (limited at runtime)
• PHP-FPM pool configuration

Caching Behavior

The postMaxSize property at src/Middleware/ValidatePostSize.php15 caches the parsed byte value. The first call to getPostMaxSize() performs the calculation; subsequent calls return the cached value at src/Middleware/ValidatePostSize.php33-35

Disabling Validation

Setting post_max_size = 0 or a negative value disables the check at src/Middleware/ValidatePostSize.php21 This is because the condition $max > 0 must be true for validation to occur.

Sources: src/Middleware/ValidatePostSize.php15 src/Middleware/ValidatePostSize.php21 src/Middleware/ValidatePostSize.php33-35 src/Middleware/ValidatePostSize.php37

Error Handling

When validation fails, the middleware throws PostTooLargeException at src/Middleware/ValidatePostSize.php22 The exception provides:

• HTTP status: 413 Payload Too Large
• Default message: "The POST data is too large."
• Optional custom headers via $headers parameter

Applications can catch PostTooLargeException to customize error responses or logging.

Sources: src/Middleware/ValidatePostSize.php22 src/Exceptions/PostTooLargeException.php15-18