Core Architecture

This section provides a comprehensive overview of the fundamental components and design patterns that comprise the Hypervel API Client system. It explains how the main classes interact, the layered architecture, and the flow of data through the system from request creation to response handling.

For step-by-step usage instructions, see Quick Start. For detailed middleware implementation, see Middleware System. For configuration options, see Configuration Reference.

Component Overview

The API client is built around five primary classes that work together to handle HTTP communication:

Component	File	Role	Template Parameters
ApiClient	src/ApiClient.php	Entry point and configuration hub	TConfig, TResource
PendingRequest	src/PendingRequest.php	Request orchestrator and middleware executor	TResource
ApiRequest	N/A (from hypervel/http-client)	PSR-7 compliant request builder	None
ApiResponse	N/A (from hypervel/http-client)	PSR-7 compliant response wrapper	None
ApiResource	N/A (to be documented in 4.7)	Response data container with array/object access	None

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

Class Responsibilities

ApiClient (4.3) serves as the factory and configuration container:

• Stores configuration via $config property src/ApiClient.php19
• Maintains resource class mapping via $resource property src/ApiClient.php24
• Manages middleware arrays via $requestMiddleware and $responseMiddleware src/ApiClient.php31-36
• Delegates HTTP method calls to PendingRequest via __call() src/ApiClient.php41-45

PendingRequest (4.4) orchestrates the entire request lifecycle:

• Inherits configuration from ApiClient in constructor src/PendingRequest.php53-62
• Builds ApiRequest instances before HTTP execution src/PendingRequest.php273
• Executes middleware pipelines src/PendingRequest.php293-307
• Wraps responses in ApiResponse src/PendingRequest.php284
• Transforms to ApiResource src/PendingRequest.php290
• Caches middleware instances in $cachedMiddleware src/PendingRequest.php51

Sources: src/ApiClient.php19-45 src/PendingRequest.php18-62 src/PendingRequest.php265-326

Architectural Layers

The system is organized into five distinct layers, each with clear responsibilities:

Sources: src/ApiClient.php14-116 src/PendingRequest.php22-342

Layer Details

Layer 1: Configuration holds all settings including:

• User-provided configuration object src/ApiClient.php19
• Target resource class for response transformation src/ApiClient.php24
• Middleware configuration arrays src/ApiClient.php31-36
• Global middleware enable/disable flag src/ApiClient.php26

Layer 2: Client Factory provides the public API:

• getClient() creates fresh PendingRequest instances src/ApiClient.php112-115
• __call() delegates HTTP methods to PendingRequest src/ApiClient.php41-45
• Exposes configuration via getter methods src/ApiClient.php52-107

Layer 3: Request Orchestration manages the request lifecycle:

• HTTP method wrappers (get(), post(), etc.) src/PendingRequest.php175-233
• sendRequest() coordinates the flow src/PendingRequest.php265-291
• Middleware pipeline execution src/PendingRequest.php293-307
• Middleware instance caching src/PendingRequest.php309-326

Layer 4: HTTP Abstraction provides PSR-7 compatibility:

• ApiRequest wraps PSR-7 requests with mutable interface
• ApiResponse wraps PSR-7 responses with mutable interface
• beforeSending() hook intercepts requests src/PendingRequest.php272-278

Layer 5: Transport handles actual HTTP communication:

• ClientPendingRequest from hypervel/http-client manages Guzzle
• Configured via withOptions() for Guzzle options src/PendingRequest.php336-338
• Always throws exceptions on HTTP errors via Http::throw() src/PendingRequest.php334

Sources: src/ApiClient.php19-115 src/PendingRequest.php175-341

Request-Response Flow

The following diagram shows the complete execution path from application code to API response:

Sources: src/ApiClient.php41-45 src/PendingRequest.php175-307

Flow Steps

1. Method Delegation: ApiClient::__call() intercepts HTTP method calls src/ApiClient.php41-45
2. Request Creation: PendingRequest is instantiated with client configuration src/ApiClient.php112-115
3. HTTP Method Call: Delegated to sendRequest() src/PendingRequest.php177
4. Client Initialization: getClient() creates ClientPendingRequest via Http::throw() src/PendingRequest.php328-341
5. Request Transformation: beforeSending() hook wraps PSR-7 in ApiRequest src/PendingRequest.php272-278
6. Request Middleware: Pipeline processes request if enabled src/PendingRequest.php274-276
7. HTTP Execution: Transport layer sends request src/PendingRequest.php278
8. Response Wrapping: Raw PSR-7 response wrapped in ApiResponse src/PendingRequest.php284
9. Response Middleware: Pipeline processes response if enabled src/PendingRequest.php286-288
10. Resource Creation: ApiResource::make() creates final data container src/PendingRequest.php290

Sources: src/PendingRequest.php265-291

Type System and Generics

The architecture uses PHP generics (via PHPDoc) to maintain type safety throughout the request-response cycle:

Template Parameters:

• TConfig: Configuration object type on ApiClient src/ApiClient.php10

  • Constrained to DataObject subclass src/ApiClient.php10
  • Accessed via getConfig() method src/ApiClient.php52-55
  • Passed to middleware constructors src/PendingRequest.php322

• TResource: Response resource type on ApiClient and PendingRequest src/ApiClient.php11 src/PendingRequest.php19

  • Constrained to ApiResource subclass src/ApiClient.php11 src/PendingRequest.php19
  • Stored as class-string<TResource> src/ApiClient.php23 src/PendingRequest.php28
  • Return type for all HTTP methods src/PendingRequest.php172-244
  • Instantiated via ::make() factory src/PendingRequest.php290

Sources: src/ApiClient.php9-24 src/PendingRequest.php18-29 src/PendingRequest.php290

Magic Method Delegation

Both ApiClient and PendingRequest use the __call() magic method to provide fluent interfaces:

ApiClient Delegation src/ApiClient.php41-45:

PendingRequest Delegation src/PendingRequest.php257-263:

This creates a seamless API where configuration methods from the underlying HTTP client are available directly on PendingRequest instances via the @mixin annotation src/PendingRequest.php20

Sources: src/ApiClient.php41-45 src/PendingRequest.php257-263

Middleware Architecture

The middleware system provides two interception points in the request-response cycle:

Pipeline	Processes	Timing	Method
Request Middleware	ApiRequest	Before HTTP execution	handleMiddlewareRequest() src/PendingRequest.php293-299
Response Middleware	ApiResponse	After HTTP execution	handleMiddlewareResponse() src/PendingRequest.php301-307

Both pipelines:

• Are executed via Pipeline from hypervel/support src/PendingRequest.php49
• Can be enabled/disabled globally src/ApiClient.php26 or per-request src/PendingRequest.php67-82
• Receive context via withContext('options', $this->middlewareOptions) src/PendingRequest.php296 src/PendingRequest.php304
• Cache middleware instances in $cachedMiddleware src/PendingRequest.php318-322

For detailed middleware documentation, see Middleware System.

Sources: src/PendingRequest.php31-51 src/PendingRequest.php293-326

Further Reading

This section provides subsections detailing each component:

• 4.1 Architecture Overview: Expanded architecture discussion with design patterns
• 4.2 Package Dependencies: Integration with hypervel/http-client and hypervel/support
• 4.3 ApiClient: Configuration, factory methods, and middleware setup
• 4.4 PendingRequest: Request orchestration, middleware execution, and HTTP delegation
• 4.5 ApiRequest: PSR-7 request building with fluent interface
• 4.6 ApiResponse: PSR-7 response wrapping and manipulation
• 4.7 ApiResource: Response data container with array/object access patterns
• 4.8 HasContext Trait: Contextual data management across request/response lifecycle

For practical usage examples, see Making Requests and Response Handling.