Advanced Features

This document provides an overview of the advanced capabilities of the Hypervel HTTP Client that extend beyond basic request/response handling. These features enable sophisticated request modification, efficient resource management, automatic error recovery, and runtime extensibility.

For basic request configuration and execution, see Making HTTP Requests. For testing features like faking and stubbing, see Testing and Mocking.

Overview

The HTTP client provides four primary advanced capabilities:

Feature	Purpose	Configuration Level
Middleware	Intercept and modify requests/responses	Global or per-request
Connection Pooling	Reuse client connections efficiently	Per-connection configuration
Retry Logic	Automatically retry failed requests	Per-request configuration
Macros	Add custom methods at runtime	Class-level extension

Each of these features is covered in detail in sections 10.1, 10.2, 10.3, and 10.4 respectively.

Middleware Architecture

The HTTP client implements a handler stack middleware system that processes requests and responses through a series of layers. Middleware can be applied globally (to all requests from a Factory) or to individual PendingRequest instances.

Handler Stack Execution Flow

The handler stack is built by PendingRequest::buildHandlerStack() and processes middleware in the following order:

1. Stub Handler - Checks for test stubs first, returns fake responses if matched
2. Recorder Handler - Records request/response pairs for testing assertions
3. Before Sending Handler - Executes callbacks registered via beforeSending()
4. User Middleware - Processes global and request-specific middleware in order
5. Base Handler - Guzzle's HTTP transport layer

Sources: src/PendingRequest.php1059-1078 src/PendingRequest.php1083-1147

Middleware Registration Methods

The following methods register middleware at different levels:

Method	Scope	Location	Line Reference
Factory::globalMiddleware()	All requests from factory	Factory.php	101-106
Factory::globalRequestMiddleware()	All requests (request mapping)	Factory.php	111-116
Factory::globalResponseMiddleware()	All requests (response mapping)	Factory.php	121-126
PendingRequest::withMiddleware()	Single request	PendingRequest.php	526-531
PendingRequest::withRequestMiddleware()	Single request (request mapping)	PendingRequest.php	536-541
PendingRequest::withResponseMiddleware()	Single request (response mapping)	PendingRequest.php	546-551
PendingRequest::beforeSending()	Single request (callback style)	PendingRequest.php	556-561

Sources: src/Factory.php101-126 src/PendingRequest.php526-561

Connection Pooling System

The Factory uses connection pooling to efficiently reuse HTTP client instances. Connections must be registered and are managed through ClientPoolProxy instances that implement object pooling.

Connection Pool Architecture

Connections are registered using Factory::registerConnection() which adds the connection name to the poolables array and stores its configuration. When PendingRequest::buildClient() is called, it resolves the appropriate client through the Factory's getClient() method.

Sources: src/Factory.php438-476 src/Factory.php73-88 src/PendingRequest.php1035-1054

Connection Configuration Flow

Sources: src/Factory.php438-476 src/PendingRequest.php1314-1323

Retry Logic and Error Recovery

The PendingRequest class implements configurable retry behavior with delays, conditional retry logic, and customizable error handling. Retries are configured using the retry() method.

Retry Configuration Parameters

The retry system is implemented in PendingRequest::send() 713-794 which wraps the request execution in a retry loop. The delay between retries can be:

• A fixed integer (milliseconds)
• A Closure that receives the attempt number and exception

Sources: src/PendingRequest.php496-508 src/PendingRequest.php108-125

Retry Execution Flow

The retry logic evaluates:

1. Whether the response was successful (status code check)
2. Whether retryWhenCallback permits retry (if provided)
3. Whether remaining attempts exist
4. Whether to throw exceptions on final failure (retryThrow)

Sources: src/PendingRequest.php731-793 src/PendingRequest.php892-946

Runtime Extension with Macros

All major classes in the HTTP client implement the Macroable trait from hyperf/macroable, allowing custom methods to be added at runtime without modifying the source code.

Classes Supporting Macros

The Macroable trait provides:

• macro() - Register a new macro method
• mixin() - Mix in methods from another class
• hasMacro() - Check if a macro is registered
• __call() - Magic method that invokes registered macros

The Factory class demonstrates macro integration at src/Factory.php34-36 where it uses the trait with a custom __call implementation that falls back to creating a new PendingRequest for undefined methods.

Sources: src/Factory.php34-36 src/PendingRequest.php41

Extension Points

The macroable architecture enables extension at multiple points in the request lifecycle:

Class	Extension Use Case	Example
Factory	Add factory-level helper methods	Custom connection builders
PendingRequest	Add request configuration shortcuts	Domain-specific auth patterns
Request	Add request inspection methods	Custom data extraction
Response	Add response parsing methods	Domain-specific transformations
ResponseSequence	Add sequence helpers	Complex fake patterns

For detailed implementation examples and best practices, see Runtime Extension with Macros.

Sources: src/Factory.php518-525 src/PendingRequest.php38-41

Integration Points

These advanced features work together to provide a comprehensive HTTP client system:

1. Middleware + Pooling: Global middleware is applied to all pooled connections
2. Middleware + Retries: Middleware executes on every retry attempt
3. Retries + Events: Event dispatching occurs on each attempt and final outcome
4. Macros + All Features: Custom methods can leverage any built-in feature

For specific implementation guidance:

• Middleware: See Middleware and Request Modification
• Pooling: See Connection Pooling
• Retries: See Retry Logic and Error Recovery
• Macros: See Runtime Extension with Macros

Sources: src/PendingRequest.php187-210 src/Factory.php404-417