Middleware Overview

This page introduces the middleware system in the Hypervel API Client, explaining the pipeline architecture and how middleware integrates into the request/response lifecycle. It covers the fundamental concepts of request and response interception points, middleware execution flow, and the role of key components in the middleware system.

For specific information about implementing request-specific middleware, see Request Middleware. For response-specific middleware, see Response Middleware. To learn how to create your own middleware classes, see Creating Custom Middleware. For detailed configuration options, see Middleware Configuration.

Purpose of Middleware

Middleware in the Hypervel API Client provides a mechanism to intercept and transform HTTP requests before they are sent and responses after they are received. This allows for cross-cutting concerns such as authentication, logging, data transformation, and error handling to be implemented in a modular and reusable way.

The middleware system operates on two distinct interception points:

Interception Point	Processing Target	Timing	Purpose
Request Middleware	ApiRequest objects	Before HTTP execution	Transform requests, add headers, modify body
Response Middleware	ApiResponse objects	After HTTP execution	Transform responses, handle errors, extract data

Sources: src/PendingRequest.php38-45 src/PendingRequest.php274-288

Pipeline Architecture

The middleware system uses a pipeline pattern implemented via the Pipeline class from hypervel/support. Each middleware array is processed sequentially, with each middleware receiving the output of the previous one.

Pipeline Execution Flow

Sources: src/PendingRequest.php293-307

The PendingRequest class orchestrates both pipelines using two key methods:

• handleMiddlewareRequest() at src/PendingRequest.php293-299 - Processes request middleware
• handleMiddlewareResponse() at src/PendingRequest.php301-307 - Processes response middleware

Both methods use the same pipeline pattern:

1. Send the request/response object into the pipeline via send()
2. Pass it through the middleware array via through()
3. Return the transformed object via thenReturn()

Integration with Request Lifecycle

Middleware is executed at specific points within the request lifecycle orchestrated by PendingRequest. The following diagram shows how middleware integrates with the core request flow:

Middleware Integration in Request Lifecycle

Sources: src/PendingRequest.php265-291

The critical code is in the sendRequest() method at src/PendingRequest.php265-291 which:

1. Creates an ApiRequest from the HTTP request at src/PendingRequest.php273
2. Conditionally applies request middleware at src/PendingRequest.php274-276
3. Executes the HTTP request at src/PendingRequest.php278
4. Creates an ApiResponse from the HTTP response at src/PendingRequest.php284
5. Conditionally applies response middleware at src/PendingRequest.php286-288
6. Transforms to ApiResource at src/PendingRequest.php290

Middleware Configuration Storage

Middleware configuration is stored in two locations:

Middleware Configuration Flow

Sources: src/ApiClient.php26-36 src/PendingRequest.php31-51

ApiClient Properties

The ApiClient class at src/ApiClient.php14-116 stores the default middleware configuration:

• $enableMiddleware at src/ApiClient.php26 - Global enable/disable flag
• $requestMiddleware at src/ApiClient.php31 - Array of request middleware class names or callables
• $responseMiddleware at src/ApiClient.php35 - Array of response middleware class names or callables

PendingRequest Properties

The PendingRequest class at src/PendingRequest.php22-342 copies these values in its constructor at src/PendingRequest.php53-62 and adds additional runtime properties:

• $middlewareOptions at src/PendingRequest.php33 - Contextual options passed to middleware
• $guzzleOptions at src/PendingRequest.php35 - HTTP client options
• $pipeline at src/PendingRequest.php49 - The Pipeline instance used for execution

Middleware Instantiation and Caching

Middleware classes are instantiated lazily when first used and cached for performance. The instantiation logic is in the createMiddleware() method:

Middleware Instantiation Logic

Sources: src/PendingRequest.php309-326

The createMiddleware() method at src/PendingRequest.php309-326:

1. Validates each middleware class exists at src/PendingRequest.php313-316
2. Checks the static cache at src/PendingRequest.php318-321
3. Instantiates new middleware with the client config at src/PendingRequest.php322
4. Stores in the cache at src/PendingRequest.php322

The cache is a static property $cachedMiddleware at src/PendingRequest.php51 which can be flushed via flushCache() at src/PendingRequest.php249-252

Context Passing

Middleware receives contextual information through the HasContext trait. The PendingRequest adds middleware options to the context before pipeline execution:

Method	Code Location	Purpose
withContext()	Used in request pipeline at src/PendingRequest.php296	Adds 'options' key with $middlewareOptions to request context
withContext()	Used in response pipeline at src/PendingRequest.php304	Adds 'options' key with $middlewareOptions to response context

Sources: src/PendingRequest.php296 src/PendingRequest.php304

Middleware can then access these options within the pipeline using the context() method provided by the HasContext trait (see HasContext Trait for details).

Enable/Disable Controls

Middleware execution can be controlled at multiple levels:

Middleware Enable/Disable Flow

Sources: src/ApiClient.php74-91 src/PendingRequest.php67-82 src/PendingRequest.php274-288

Global Level (ApiClient)

• enableMiddleware() at src/ApiClient.php76-81 - Enables middleware for all requests from this client
• disableMiddleware() at src/ApiClient.php86-91 - Disables middleware for all requests from this client
• getEnableMiddleware() at src/ApiClient.php68-71 - Returns current state

Per-Request Level (PendingRequest)

• enableMiddleware() at src/PendingRequest.php67-72 - Enables middleware for this specific request
• disableMiddleware() at src/PendingRequest.php77-82 - Disables middleware for this specific request

The runtime checks occur at:

• src/PendingRequest.php274 - Request middleware conditional
• src/PendingRequest.php286 - Response middleware conditional

Key Components Summary

Component	Role	Key Methods/Properties
ApiClient	Stores default middleware configuration	$requestMiddleware, $responseMiddleware, $enableMiddleware at src/ApiClient.php26-36
PendingRequest	Orchestrates middleware execution	handleMiddlewareRequest(), handleMiddlewareResponse(), createMiddleware() at src/PendingRequest.php293-326
Pipeline	Executes middleware in sequence	send(), through(), thenReturn() (from hypervel/support)
ApiRequest	Request object passed through request pipeline	See ApiRequest for details
ApiResponse	Response object passed through response pipeline	See ApiResponse for details

Sources: src/ApiClient.php1-116 src/PendingRequest.php1-342