Overview

This document provides a high-level introduction to the Hypervel API Client, a PHP library for building type-safe, middleware-enabled HTTP API clients. This overview covers the package's purpose, architecture, and core components. For installation instructions, see Installation. For a quick working example, see Quick Start. For detailed component documentation, see Core Architecture.

What is Hypervel API Client

Hypervel API Client is a PHP 8.2+ library that provides a fluent, type-safe interface for interacting with HTTP APIs. Built on PSR-7 standards, it offers a middleware-enabled architecture for request/response transformation, with support for custom resource types and configuration objects.

The package is designed as a foundation for building custom API clients. Rather than making direct HTTP calls, developers extend ApiClient to create domain-specific clients with built-in configuration, authentication, and response handling.

Sources: composer.json1-42 src/ApiClient.php1-117

Key Features

Feature	Description	Related Documentation
Type-Safe Resources	Generic type support for configuration and response objects using PHP templates	Type Safety
PSR-7 Compliant	Full compatibility with PSR-7 HTTP message standards	ApiRequest, ApiResponse
Middleware Pipeline	Dual pipelines for request and response interception	Middleware System
Fluent Interface	Method chaining for readable request building	Fluent Interface Patterns
Context Management	Attach metadata to requests/responses throughout lifecycle	Context Management
Flexible Configuration	DataObject-based configuration with optional typing	Configuration Reference

Sources: src/ApiClient.php1-117 composer.json23-26

Core Components

The library consists of five primary classes that work together to handle the complete request/response lifecycle:

Component Roles:

Component	Class Name	Primary Responsibility
Entry Point	ApiClient	Configuration storage, middleware setup, factory for PendingRequest
Orchestrator	PendingRequest	Request building, middleware execution, HTTP transport coordination
Request Builder	ApiRequest	PSR-7 request construction with fluent API
Response Wrapper	ApiResponse	PSR-7 response wrapping with mutation support
Data Container	ApiResource	Convenient access to response data via array/object syntax

Sources: src/ApiClient.php1-117

Request Lifecycle

The following diagram illustrates how a typical API request flows through the system, from application code to final response:

Lifecycle Stages:

1. Invocation: Application calls HTTP method on ApiClient (via __call magic method delegation)
2. Factory: ApiClient creates a new PendingRequest instance with configuration
3. Building: PendingRequest constructs an ApiRequest with URL, method, headers, and body
4. Request Middleware: If enabled, request passes through middleware pipeline for transformation
5. Execution: HTTP request sent via hypervel/http-client to external API
6. Wrapping: Response wrapped in ApiResponse for PSR-7 compliance and mutation support
7. Response Middleware: If enabled, response passes through middleware pipeline for transformation
8. Transformation: ApiResponse transformed into ApiResource for convenient data access
9. Return: Final ApiResource returned to application code

Sources: src/ApiClient.php41-45 src/ApiClient.php112-115

Package Dependencies

Hypervel API Client relies on two external packages from the Hypervel ecosystem:

Package	Version	Purpose
hypervel/http-client	^0.3	Provides HTTP transport layer and base request/response classes that ApiRequest and ApiResponse extend
hypervel/support	^0.3	Supplies utilities including DataObject for configuration and Pipeline for middleware execution

The library requires PHP 8.2 or higher to leverage native type system features including generics support via PHPDoc annotations.

Architecture Integration:

For detailed dependency information, see Package Dependencies.

Sources: composer.json23-26

Design Philosophy

The Hypervel API Client is architected around several key design principles:

Separation of Concerns

• ApiClient handles configuration and factory responsibilities
• PendingRequest orchestrates the request lifecycle
• ApiRequest and ApiResponse manage PSR-7 compliance
• ApiResource provides application-friendly data access

Type Safety Generic type parameters (TConfig, TResource) flow through the entire system, allowing IDEs and static analysis tools to provide accurate type hints and catch errors at development time. See Type Safety for implementation details.

Extensibility The middleware pipeline architecture allows modification of requests before sending and responses after receiving without changing core library code. See Middleware System for usage patterns.

Fluent Interfaces Method chaining is used throughout the library to create readable, self-documenting code. The ApiClient delegates method calls to PendingRequest via the __call magic method src/ApiClient.php41-45 enabling transparent request building.

Immutability with Pragmatism While ApiRequest and ApiResponse use immutable-style fluent interfaces (returning new instances), the library balances purity with practicality for middleware scenarios where mutation is more efficient.

Sources: src/ApiClient.php1-117

Template Type Parameters

The library uses PHP template annotations for compile-time type safety:

Template Parameter	Scope	Purpose
TConfig	ApiClient	Type of configuration object (extends DataObject)
TResource	ApiClient, PendingRequest	Type of resource returned by API methods

Example type flow:

This ensures that when you create an ApiClient<UserConfig, UserResource>, all methods return instances of UserResource, providing full IDE autocomplete and static analysis support.

Sources: src/ApiClient.php10-12

Next Steps

• Installation: See Installation for Composer setup instructions
• Quick Start: See Quick Start for a complete working example
• Core Components: See Core Architecture for detailed component documentation
• Making Requests: See Making Requests for HTTP method usage and configuration
• Middleware: See Middleware System for extending request/response processing

Sources: README.md1-3 composer.json1-42