Overview

The Hypervel HTTP Client is a fluent, feature-rich HTTP client library built on top of Guzzle. It provides an expressive API for making HTTP requests with built-in support for testing, event dispatching, connection pooling, and advanced request/response handling. This page introduces the library's architecture, core components, and key capabilities.

For installation instructions, see Installation and Setup. For hands-on examples to get started quickly, see Quick Start Guide.

Sources: composer.json1-43 src/Factory.php1-526 src/PendingRequest.php1-1335

---

Purpose and Scope

This library serves as an HTTP client abstraction layer that:

• Simplifies HTTP request construction and execution using a fluent interface
• Wraps Guzzle's ClientInterface with enhanced features for testing and monitoring
• Provides comprehensive testing utilities including request faking, recording, and assertions
• Dispatches events at key lifecycle points for observability
• Manages connection pooling for efficient resource utilization
• Offers PSR-7 compliant request/response handling with developer-friendly extensions

The library is designed for PHP 8.2+ applications and integrates seamlessly with frameworks using PSR-7 and PSR-14 event dispatcher interfaces.

Sources: composer.json28-33 src/Factory.php93-96

---

Architecture Overview

The library follows a layered architecture with clear separation of concerns:

Architecture: Core System Layers

The architecture consists of four primary layers:

1. API Layer: Factory and PendingRequest provide the developer-facing interface
2. Data Layer: Request and Response wrap PSR-7 interfaces with enhanced functionality
3. Transport Layer: Guzzle Client, HandlerStack middleware, and optional connection pooling
4. Support Systems: Event dispatching and testing infrastructure

Sources: src/Factory.php31-36 src/PendingRequest.php38-41

---

Core Components

Component	File	Role	Key Responsibilities
Factory	src/Factory.php	Client factory and test coordinator	Creates PendingRequest instances, manages global middleware/options, handles request faking and recording, provides test assertions
PendingRequest	src/PendingRequest.php	Fluent request builder and executor	Configures request options (headers, auth, body, etc.), builds Guzzle client and handler stack, executes HTTP requests, manages retry logic
Request	src/Request.php	Request data accessor	Wraps PSR-7 RequestInterface, provides convenient data access methods
Response	src/Response.php	Response data processor	Wraps PSR-7 ResponseInterface, decodes JSON, provides status checking, converts to collections/fluent objects
ClientPoolProxy	src/ClientPoolProxy.php	Connection pool manager	Wraps Guzzle clients for connection reuse and pooling
ResponseSequence	src/ResponseSequence.php	Test utility	Returns ordered fake responses for testing sequential requests

Sources: src/Factory.php28-36 src/PendingRequest.php38-210

---

Key Features

Fluent Request Configuration

The library uses method chaining for intuitive request construction:

Configuration methods are available on both Factory (global) and PendingRequest (per-request).

Sources: src/PendingRequest.php215-521

Comprehensive Testing Support

Built-in faking, recording, and assertion capabilities eliminate the need for external mocking libraries:

• Faking: Intercept requests and return fake responses without network calls
• Recording: Capture all request/response pairs for verification
• Assertions: Verify specific requests were sent with expected data
• Sequences: Return ordered responses for testing multi-step workflows

Sources: src/Factory.php183-260 src/Factory.php288-382

Event System Integration

Three events provide hooks for logging, monitoring, and custom behavior:

• RequestSending: Dispatched before sending each request
• ResponseReceived: Dispatched after receiving a successful response
• ConnectionFailed: Dispatched when connection fails

Sources: src/PendingRequest.php1252-1280 src/Events/RequestSending.php src/Events/ResponseReceived.php src/Events/ConnectionFailed.php

Automatic Retry Logic

Configurable retry behavior with customizable delay and retry conditions:

Sources: src/PendingRequest.php494-508 src/PendingRequest.php729-793

Connection Pooling

Named connection configurations with automatic pooling for improved performance:

Sources: src/Factory.php436-476 src/ClientPoolProxy.php

PSR Standards Compliance

• PSR-7: Full HTTP message interface compatibility
• PSR-14: Event dispatcher integration for observability

Sources: src/PendingRequest.php31-32 src/Factory.php23

---

Request Lifecycle

Request Lifecycle: From API Call to Response

Key lifecycle stages:

1. Initialization: Factory creates PendingRequest with global middleware and stub callbacks
2. Configuration: Request is configured via fluent methods (headers, timeout, etc.)
3. Handler Stack Building: Middleware, recorder, and stub handlers are pushed to the stack
4. Event Dispatch: RequestSending event fires before execution
5. Execution: Either stubbed response returns or Guzzle makes real HTTP request
6. Recording: Request/response pair recorded if testing mode is active
7. Response Wrapping: PSR-7 response wrapped in Response object
8. Event Dispatch: ResponseReceived event fires after successful response
9. Return: Response object returned to application

Sources: src/PendingRequest.php713-794 src/PendingRequest.php1057-1145 src/Factory.php402-417

---

Component Interaction Map

Component Interaction: Method-Level View

This diagram shows the actual methods called during request execution:

1. Factory::createPendingRequest() instantiates new PendingRequest
2. PendingRequest::send() orchestrates the request lifecycle
3. PendingRequest::buildHandlerStack() creates the middleware pipeline
4. PendingRequest::buildClient() creates/retrieves Guzzle client
5. Request wraps PSR-7 request for data access
6. Client::request() performs HTTP transport
7. Response wraps PSR-7 response with enhanced methods
8. Application receives Response object

Sources: src/Factory.php402-417 src/PendingRequest.php713-794 src/PendingRequest.php1057-1145

---

Testing Infrastructure

Testing Infrastructure: Fake-Record-Assert Pattern

The testing system follows a three-phase pattern:

1. Fake: Configure stub callbacks to intercept requests
2. Record: Capture all request/response pairs
3. Assert: Verify expected requests were sent with correct data

Key testing classes:

• Factory: Manages faking and provides assertions src/Factory.php183-382
• ResponseSequence: Returns ordered responses src/ResponseSequence.php
• PendingRequest::buildStubHandler(): Intercepts requests src/PendingRequest.php1112-1145
• PendingRequest::buildRecorderHandler(): Records pairs src/PendingRequest.php1091-1109

Sources: src/Factory.php183-382 src/PendingRequest.php1091-1145

---

Extension Points

The library provides multiple extension mechanisms:

Extension Point	Trait/Interface	Classes	Purpose
Macros	Macroable	Factory, PendingRequest, Request, Response	Add custom methods at runtime
Middleware	Handler stack	PendingRequest	Intercept and modify requests/responses
Events	EventDispatcherInterface	Factory	Hook into request lifecycle
Connection pooling	HasPoolProxy	Factory	Custom connection management strategies

Sources: src/Factory.php33-36 src/PendingRequest.php40-41 composer.json30

---

Dependencies

The library has minimal external dependencies:

Package	Version	Purpose
php	^8.2	Runtime environment
guzzlehttp/guzzle	^7.8.2	HTTP transport layer
guzzlehttp/uri-template	^1.0	URI parameter expansion
hyperf/macroable	~3.1.0	Runtime method extension
hypervel/support	^0.3	Collection and utility classes

Sources: composer.json28-33

---

Next Steps

• For installation instructions, see Installation and Setup
• For quick examples to start making requests, see Quick Start Guide
• For detailed component documentation, see Core Components
• For testing strategies, see Testing and Mocking