Core Components

This page provides an overview of the four main classes that form the foundation of the Hypervel HTTP Client library and describes their relationships. For detailed documentation of individual classes and their methods, see Factory, PendingRequest, Request, and Response.

Component Overview

The Hypervel HTTP Client is built around four core classes that work together to provide a fluent API for making HTTP requests:

Component	Purpose	File Location	Primary Responsibilities
Factory	Entry point and request factory	src/Factory.php	Creates PendingRequest instances, manages global configuration, handles testing/mocking features
PendingRequest	Request builder and executor	src/PendingRequest.php	Configures request options, builds Guzzle handler stack, executes HTTP requests, manages middleware
Request	Request data accessor	src/Request.php	Wraps PSR-7 RequestInterface, provides convenient access to request data, headers, and body
Response	Response processor	src/Response.php	Wraps PSR-7 ResponseInterface, decodes JSON, checks status codes, provides collection/fluent interfaces

All four classes implement the Macroable trait from Hyperf, enabling runtime extension through macros src/Factory.php34-36 src/PendingRequest.php41 src/Request.php16 src/Response.php27-29

Sources: src/Factory.php src/PendingRequest.php src/Request.php src/Response.php

Component Relationships

Diagram: Core Component Architecture

Sources: src/Factory.php404-417 src/PendingRequest.php187-210 src/PendingRequest.php1205-1208 src/Request.php26-28 src/Response.php54-56

Factory Component

The Factory class serves as the entry point for creating HTTP requests. It maintains global configuration and provides testing utilities.

Key Properties:

• $globalMiddleware - Middleware applied to every request src/Factory.php41
• $globalOptions - Options applied to every request src/Factory.php46
• $stubCallbacks - Collection of stub callbacks for testing src/Factory.php51
• $recording - Flag indicating if requests are being recorded src/Factory.php56
• $recorded - Array of recorded request/response pairs src/Factory.php61

Key Methods:

• createPendingRequest() - Creates a new PendingRequest instance src/Factory.php404-409
• fake() - Enables request stubbing for testing src/Factory.php183-224
• assertSent() - Asserts a request was sent src/Factory.php311-317

The Factory uses the __call() magic method to proxy method calls to a new PendingRequest instance src/Factory.php518-525 enabling fluent syntax like $factory->get($url).

Sources: src/Factory.php31-96 src/Factory.php404-525

PendingRequest Component

The PendingRequest class is the request builder and execution engine. It provides a fluent interface for configuring request options and executes the request through Guzzle.

Key Properties:

• $factory - Reference to parent Factory src/PendingRequest.php188
• $client - Guzzle client instance src/PendingRequest.php46
• $baseUrl - Base URL for requests src/PendingRequest.php58
• $options - Request options array src/PendingRequest.php93
• $middleware - User-added middleware src/PendingRequest.php145
• $beforeSendingCallbacks - Callbacks executed before sending src/PendingRequest.php130

Request Execution Flow:

1. Configure request using fluent methods (withHeaders(), timeout(), etc.)
2. Call HTTP verb method (get(), post(), etc.) src/PendingRequest.php624-705
3. Build handler stack with middleware src/PendingRequest.php1057-1076
4. Execute request through Guzzle src/PendingRequest.php953-972
5. Wrap response in Response object src/PendingRequest.php1205-1208

Sources: src/PendingRequest.php38-210 src/PendingRequest.php624-794 src/PendingRequest.php1057-1208

Request Component

The Request class wraps a PSR-7 RequestInterface and provides convenient methods for accessing request data.

Key Properties:

• $request - The underlying PSR-7 request src/Request.php26
• $data - Decoded payload (form params or JSON) src/Request.php21

Key Methods:

• method() - Get HTTP method src/Request.php33-36
• url() - Get request URL src/Request.php41-44
• headers() - Get request headers src/Request.php95-98
• body() - Get request body src/Request.php103-106
• data() - Get decoded request data src/Request.php127-137
• isJson() - Check if request is JSON src/Request.php176-180
• isForm() - Check if request is form data src/Request.php168-171

The class implements ArrayAccess to enable array-like access to request data src/Request.php14 src/Request.php241-278

Sources: src/Request.php14-28 src/Request.php33-137

Response Component

The Response class wraps a PSR-7 ResponseInterface and provides rich data extraction and status checking capabilities.

Key Properties:

• $response - The underlying PSR-7 response src/Response.php54
• $decoded - Cached decoded JSON response src/Response.php34
• $cookies - Request cookies src/Response.php44
• $transferStats - Transfer statistics src/Response.php49

Key Methods:

Data Extraction:

• body() - Get response body as string src/Response.php61-64
• json() - Decode JSON with dot notation support src/Response.php69-80
• collect() - Get response as Collection src/Response.php129-132
• fluent() - Get response as Fluent object src/Response.php137-140

Status Checking:

• successful() - Check if 2xx status src/Response.php197-200
• failed() - Check if 4xx or 5xx status src/Response.php213-216
• clientError() - Check if 4xx status src/Response.php221-224
• serverError() - Check if 5xx status src/Response.php229-232

The class uses the DeterminesStatusCode trait for semantic status checking methods src/Response.php27

Sources: src/Response.php22-56 src/Response.php61-140 src/Response.php197-232

Component Interaction Flow

Diagram: Request Lifecycle Through Components

Sources: src/Factory.php518-525 src/PendingRequest.php713-794 src/PendingRequest.php953-972 src/PendingRequest.php1205-1208 src/Response.php69-80

Handler Stack and Middleware Architecture

The PendingRequest builds a Guzzle HandlerStack with multiple layers of middleware:

Diagram: Handler Stack Construction

Handler Stack Construction Process:

1. Base Handler - Created with optional custom handler src/PendingRequest.php1057-1060
2. User Middleware - Added from $middleware collection src/PendingRequest.php1068-1070
3. Before Sending Handler - Executes before-sending callbacks src/PendingRequest.php1081-1088
4. Recorder Handler - Records request/response pairs for testing src/PendingRequest.php1093-1109
5. Stub Handler - Intercepts requests with fake responses src/PendingRequest.php1114-1145

The handlers are pushed onto the stack, so they execute in reverse order (stub handler runs first, base handler runs last).

Sources: src/PendingRequest.php1057-1145

PSR-7 Integration

All request and response handling is built on PSR-7 interfaces:

Class	PSR-7 Interface	Wrapper Method	Unwrap Method
Request	Psr\Http\Message\RequestInterface	Constructor src/Request.php26-28	toPsrRequest() src/Request.php231-234
Response	Psr\Http\Message\ResponseInterface	Constructor src/Response.php54-56	toPsrResponse() src/Response.php275-278

This design allows the Hypervel HTTP Client to:

• Work seamlessly with Guzzle (which uses PSR-7)
• Provide enhanced APIs while maintaining PSR-7 compatibility
• Enable easy integration with other PSR-7-compliant libraries

Sources: src/Request.php26-28 src/Request.php231-234 src/Response.php54-56 src/Response.php275-278

Extensibility Through Macros

All four core components implement the Macroable trait, enabling runtime extension:

This allows users to add custom methods at runtime without modifying the core classes. For details on using macros, see Runtime Extension with Macros.

Sources: src/Factory.php34-36 src/PendingRequest.php41 src/Request.php16 src/Response.php27-29

Connection Management

The Factory manages HTTP client connections and supports connection pooling:

Key Properties:

• $poolables - Connections that use connection pooling src/Factory.php78
• $connections - Resolved client connections src/Factory.php83
• $connectionConfigs - Configuration for connections src/Factory.php88

Connection Resolution:

1. PendingRequest calls buildClient() src/PendingRequest.php1033-1036
2. Calls Factory->getClient() with connection name src/PendingRequest.php1036
3. Factory resolves connection through resolve() method src/Factory.php461-476
4. Returns either direct Client or ClientPoolProxy src/Factory.php471-475

For more details on connection management, see Connection Management.

Sources: src/Factory.php436-487 src/PendingRequest.php1033-1052

Testing Infrastructure

The core components include built-in testing support:

Factory Testing Features:

• fake() - Register stub callbacks src/Factory.php183-224
• stubUrl() - Stub specific URLs src/Factory.php239-260
• recordRequestResponsePair() - Record requests src/Factory.php301-306
• assertSent() - Assert request was sent src/Factory.php311-317
• assertNotSent() - Assert request was not sent src/Factory.php344-350

PendingRequest Testing Features:

• stub() - Register stub callbacks src/PendingRequest.php1213-1220
• preventStrayRequests() - Throw if unfaked request src/PendingRequest.php1225-1230
• Stub handler in middleware stack src/PendingRequest.php1114-1145

For complete testing documentation, see Testing and Mocking.

Sources: src/Factory.php183-399 src/PendingRequest.php1114-1230