ApiClient

The ApiClient class serves as the primary entry point and orchestrator for the hypervel/api-client package. It manages global configuration settings, middleware pipelines, resource type definitions, and acts as a factory for creating PendingRequest instances. The class uses magic method delegation to provide a fluent interface that forwards method calls to the underlying request builder.

For detailed information about request building and execution, see PendingRequest. For configuration options and the DataObject system, see Configuration.

Class Structure

The ApiClient class is defined as a generic class with two type parameters that maintain type safety throughout the request lifecycle.

Sources: src/ApiClient.php1-116

Properties

The ApiClient maintains five core properties that define its behavior and configuration:

Property	Type	Default	Purpose
$config	?DataObject	null	Stores client configuration as a DataObject instance
$resource	string	ApiResource::class	Class name of the resource type to return from requests
$enableMiddleware	bool	true	Global flag to enable/disable middleware processing
$requestMiddleware	array	[]	Array of request middleware class names or instances
$responseMiddleware	array	[]	Array of response middleware class names or instances

Sources: src/ApiClient.php16-36

Generic Type Parameters

The class uses two generic type parameters to maintain type safety:

• TConfig extends DataObject: Defines the configuration object type, allowing subclasses to specify custom configuration structures
• TResource extends ApiResource: Defines the resource type returned by API requests, enabling strongly-typed responses

Sources: src/ApiClient.php10-11 src/ApiClient.php17-24

Configuration Management

The ApiClient provides a simple getter for accessing the client configuration. Configuration is typically set by subclasses during instantiation.

Configuration Access

The getConfig() method returns the configuration object, or null if no configuration has been set:

Sources: src/ApiClient.php48-55

Middleware Configuration

The ApiClient manages global middleware settings that are inherited by all PendingRequest instances created from this client. Middleware can be enabled or disabled, and specific middleware classes can be configured for request and response processing.

Middleware State Management

Middleware Control Methods

Method	Return Type	Purpose
getEnableMiddleware()	bool	Returns whether middleware is currently enabled
enableMiddleware()	static	Enables middleware processing for all requests
disableMiddleware()	static	Disables middleware processing for all requests
getRequestMiddleware()	array	Returns the array of request middleware classes
getResponseMiddleware()	array	Returns the array of response middleware classes

Sources: src/ApiClient.php66-107

Middleware Inheritance

When a PendingRequest is created, it inherits the middleware configuration from the parent ApiClient:

Sources: src/PendingRequest.php48-55

Factory Pattern

The ApiClient implements the Factory pattern through its getClient() method, which creates and returns new PendingRequest instances. This design ensures that each API request operates with a fresh request builder while inheriting the parent client's configuration.

Request Creation Flow

Factory Method Implementation

The getClient() method is straightforward, instantiating a new PendingRequest and passing $this as the client reference:

Each call to getClient() produces a new, independent PendingRequest instance that can be configured without affecting other requests.

Sources: src/ApiClient.php109-115

Magic Method Delegation

The ApiClient uses PHP's __call magic method to provide a fluent interface that transparently delegates method calls to PendingRequest instances. This pattern allows the client to expose the full PendingRequest API without explicitly defining wrapper methods.

Delegation Mechanism

Implementation Details

The __call method implementation:

This two-line implementation:

1. Creates a new PendingRequest via getClient()
2. Forwards the method call with all parameters using argument unpacking
3. Returns the result directly to the caller

Sources: src/ApiClient.php39-45

Method Resolution Order

When a method is called on ApiClient:

This allows ApiClient to expose methods like:

• get(), post(), put(), patch(), delete(), head() - HTTP methods
• send() - Generic request sender
• withRequestMiddleware(), withResponseMiddleware() - Per-request middleware
• enableMiddleware(), disableMiddleware() - Per-request middleware control
• Any other fluent builder methods from PendingRequest or ClientPendingRequest

Sources: src/ApiClient.php39-45 src/PendingRequest.php163-226

PHPDoc Mixin Annotation

The ApiClient class includes a mixin annotation that provides IDE autocomplete support:

This annotation tells IDEs and static analysis tools that ApiClient should be treated as if it implements all public methods from PendingRequest, even though the actual implementation uses magic method delegation. This provides better developer experience with autocomplete and type hints.

Sources: src/ApiClient.php12

Usage Pattern

The typical usage pattern for ApiClient involves:

1. Subclassing: Create a concrete subclass that defines resource types and middleware
2. Configuration: Set up configuration in the constructor
3. Request Execution: Use the fluent interface to make requests

Sources: src/ApiClient.php1-116

Relationship to PendingRequest

The ApiClient and PendingRequest have a tightly coupled relationship where ApiClient serves as the configuration store and factory, while PendingRequest handles the actual request building and execution:

Responsibility	ApiClient	PendingRequest
Configuration Storage	✓	Inherits from client
Middleware Configuration	✓	Inherits, can override
Request Creation	Factory method	✗
Request Building	Delegates	✓
Request Execution	Delegates	✓
HTTP Client Management	✗	✓
Resource Creation	✗	✓

Sources: src/ApiClient.php1-116 src/PendingRequest.php48-55