Configuration Reference

This document provides a comprehensive reference of all configuration options available in the hypervel/api-client package. Configuration operates at two levels: client-level settings defined through ApiClient properties, and request-level settings that override or extend the client configuration via PendingRequest methods.

---

Configuration Architecture

The API client uses a two-layer configuration architecture where settings flow from ApiClient to PendingRequest:

Configuration Layer Hierarchy

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

Complete Configuration Properties

ApiClient Properties

Property	Type	Default	Scope	Description
$config	DataObject|null	null	Client	Custom configuration object for application-specific settings
$resource	class-string<TResource>	ApiResource::class	Client	Default resource class for response transformation
$enableMiddleware	bool	true	Client	Master switch for middleware processing
$requestMiddleware	array	[]	Client	Ordered list of request middleware class names
$responseMiddleware	array	[]	Client	Ordered list of response middleware class names

Sources: src/ApiClient.php16-36

PendingRequest Properties

Property	Type	Default	Scope	Description
$resource	class-string<TResource>	Inherited	Request	Resource class for this request (overrides client default)
$enableMiddleware	bool	Inherited	Request	Middleware enable flag for this request
$middlewareOptions	array	[]	Request	Options passed to middleware via context
$guzzleOptions	array	[]	Request	Guzzle HTTP client configuration options
$requestMiddleware	array	Inherited	Request	Request middleware for this request
$responseMiddleware	array	Inherited	Request	Response middleware for this request
$request	ClientPendingRequest|null	null	Request	Cached HTTP client instance
$pipeline	Pipeline	Auto-created	Request	Middleware pipeline processor
$cachedMiddleware	array (static)	[]	Static	Cached middleware instances

Sources: src/PendingRequest.php27-51

---

Client-Level Configuration

The ApiClient class stores configuration that applies to all requests. Configuration is set by extending ApiClient and defining protected properties.

Configuration Object ($config)

The $config property stores application-specific configuration using DataObject from hypervel/support.

Property Details:

• Type: DataObject|null
• Default: null
• Generic Type: TConfig of DataObject
• Access: Via getConfig() method src/ApiClient.php52-55
• Middleware Access: Passed to middleware constructors src/PendingRequest.php322

Usage Pattern:

Sources: src/ApiClient.php16-55 src/PendingRequest.php322

Resource Class ($resource)

The $resource property defines the class used to transform HTTP responses into typed resource objects.

Property Details:

• Type: class-string<TResource>
• Default: ApiResource::class
• Constraint: Must extend ApiResource
• Access: Via getResource() method src/ApiClient.php60-63
• Override: Can be overridden per-request via withResource() src/PendingRequest.php150-167

Usage Pattern:

Sources: src/ApiClient.php22-63 src/PendingRequest.php29-290

Middleware Enable Flag ($enableMiddleware)

The $enableMiddleware property serves as a master switch for all middleware processing.

Property Details:

• Type: bool
• Default: true
• Access: Via getEnableMiddleware() method src/ApiClient.php68-71
• Methods: enableMiddleware(), disableMiddleware() src/ApiClient.php74-91
• Effect: When false, both request and response middleware pipelines are skipped src/PendingRequest.php274-286

Sources: src/ApiClient.php26-91 src/PendingRequest.php274-288

Request Middleware ($requestMiddleware)

The $requestMiddleware property contains an ordered list of middleware classes that process requests before HTTP execution.

Property Details:

• Type: array<callable|object|string>
• Default: []
• Access: Via getRequestMiddleware() method src/ApiClient.php96-99
• Execution Order: Sequential, in array order
• Instantiation: Each class instantiated with $config object src/PendingRequest.php322
• Caching: Instances cached in static property src/PendingRequest.php318-322

Usage Pattern:

Sources: src/ApiClient.php29-99 src/PendingRequest.php40-326

Response Middleware ($responseMiddleware)

The $responseMiddleware property contains an ordered list of middleware classes that process responses after HTTP execution.

Property Details:

• Type: array<callable|object|string>
• Default: []
• Access: Via getResponseMiddleware() method src/ApiClient.php104-107
• Execution Order: Sequential, in array order
• Instantiation: Each class instantiated with $config object src/PendingRequest.php322
• Caching: Instances cached in static property src/PendingRequest.php318-322

Usage Pattern:

Sources: src/ApiClient.php33-107 src/PendingRequest.php45-326

---

Request-Level Configuration

PendingRequest instances inherit configuration from ApiClient and can override or extend settings on a per-request basis.

Configuration Inheritance

Configuration Copy Process

Sources: src/PendingRequest.php53-62 src/ApiClient.php112-115

Middleware Options ($middlewareOptions)

The $middlewareOptions property passes contextual data to middleware.

Property Details:

• Type: array
• Default: []
• Method: withMiddlewareOptions(array $options) src/PendingRequest.php87-92
• Context Injection: Attached via withContext('options', $middlewareOptions) src/PendingRequest.php296-304
• Middleware Access: Retrieved via getContext('options') from request/response objects

Data Flow:

Usage Pattern:

Sources: src/PendingRequest.php33-304

Guzzle Options ($guzzleOptions)

The $guzzleOptions property configures the underlying Guzzle HTTP client.

Property Details:

• Type: array
• Default: []
• Method: withGuzzleOptions(array $options) src/PendingRequest.php97-102
• Application: Applied via withOptions() when creating HTTP client src/PendingRequest.php336-338
• Documentation: See Guzzle Request Options

Common Guzzle Options:

Option	Type	Description	Example
timeout	float	Total request timeout in seconds	30.0
connect_timeout	float	Connection timeout in seconds	5.0
verify	bool|string	SSL certificate verification	true or /path/to/cert.pem
proxy	string|array	HTTP proxy configuration	'tcp://proxy.example.com:8080'
allow_redirects	bool|array	Redirect behavior	['max' => 5, 'strict' => true]
http_errors	bool	Throw exceptions on 4xx/5xx	false
headers	array	Additional HTTP headers	['User-Agent' => 'MyApp/1.0']
query	array	Query string parameters	['page' => 1, 'limit' => 10]
json	array	JSON request body	['name' => 'John']
form_params	array	Form-encoded request body	['field' => 'value']
auth	array	HTTP authentication	['user', 'pass', 'basic']
cert	string|array	Client-side certificate	'/path/to/cert.pem'
ssl_key	string|array	SSL private key	'/path/to/key.pem'
debug	bool|resource	Debug output	true

Application Flow:

Usage Pattern:

Sources: src/PendingRequest.php35-341

Resource Override (withResource())

The withResource() method overrides the client's default resource class for a specific request.

Method Details:

• Signature: withResource(string $resource): static
• Location: src/PendingRequest.php150-167
• Validation:
  • Checks class_exists($resource) src/PendingRequest.php152
  • Checks is_subclass_of($resource, ApiResource::class) src/PendingRequest.php158
• Exception: Throws InvalidArgumentException if validation fails
• Usage: Applied in sendRequest() src/PendingRequest.php290

Usage Pattern:

Sources: src/PendingRequest.php29-290

---

Configuration Methods Reference

ApiClient Methods

Methods for accessing and modifying client-level configuration:

Method	Signature	Return Type	Location	Description
getConfig()	getConfig()	DataObject|null	src/ApiClient.php52-55	Returns the custom configuration object
getResource()	getResource()	string	src/ApiClient.php60-63	Returns the default resource class name
getEnableMiddleware()	getEnableMiddleware()	bool	src/ApiClient.php68-71	Returns whether middleware is enabled
enableMiddleware()	enableMiddleware()	static	src/ApiClient.php74-81	Enables middleware processing, returns $this
disableMiddleware()	disableMiddleware()	static	src/ApiClient.php86-91	Disables middleware processing, returns $this
getRequestMiddleware()	getRequestMiddleware()	array	src/ApiClient.php96-99	Returns the request middleware array
getResponseMiddleware()	getResponseMiddleware()	array	src/ApiClient.php104-107	Returns the response middleware array
getClient()	getClient()	PendingRequest	src/ApiClient.php112-115	Creates and returns a new PendingRequest instance

Sources: src/ApiClient.php48-115

PendingRequest Configuration Methods

Methods for per-request configuration overrides:

Method	Signature	Return Type	Location	Description
enableMiddleware()	enableMiddleware()	static	src/PendingRequest.php67-72	Enables middleware for this request
disableMiddleware()	disableMiddleware()	static	src/PendingRequest.php77-82	Disables middleware for this request
withMiddlewareOptions()	withMiddlewareOptions(array $options)	static	src/PendingRequest.php87-92	Sets options passed to middleware
withGuzzleOptions()	withGuzzleOptions(array $options)	static	src/PendingRequest.php97-102	Sets Guzzle HTTP client options
withRequestMiddleware()	withRequestMiddleware(array $middleware)	static	src/PendingRequest.php107-112	Replaces request middleware array
withAddedRequestMiddleware()	withAddedRequestMiddleware(array $middleware)	static	src/PendingRequest.php117-122	Appends to existing request middleware
withResponseMiddleware()	withResponseMiddleware(array $middleware)	static	src/PendingRequest.php127-132	Replaces response middleware array
withAddedResponseMiddleware()	withAddedResponseMiddleware(array $middleware)	static	src/PendingRequest.php137-142	Appends to existing response middleware
withResource()	withResource(string $resource)	static	src/PendingRequest.php150-167	Sets resource class for this request
flushCache()	flushCache()	void	src/PendingRequest.php249-252	Clears cached middleware instances

All methods except flushCache() return static to enable method chaining.

Sources: src/PendingRequest.php67-252

Middleware Array Methods

Detailed comparison of middleware array manipulation methods:

Method	Effect	Use Case
withRequestMiddleware([...])	Replaces entire array	Completely customize request middleware for one request
withAddedRequestMiddleware([...])	Appends to existing array	Add additional request middleware while keeping client defaults
withResponseMiddleware([...])	Replaces entire array	Completely customize response middleware for one request
withAddedResponseMiddleware([...])	Appends to existing array	Add additional response middleware while keeping client defaults

Implementation Details:

• Replace: $this->requestMiddleware = $middleware; src/PendingRequest.php109
• Append: $this->requestMiddleware = array_merge($this->requestMiddleware, $middleware); src/PendingRequest.php119

Sources: src/PendingRequest.php107-142

---

Method Chaining Patterns

Configuration methods return static to enable fluent method chaining.

Method Chaining Flow

Chaining Examples:

Magic Method Delegation:

• ApiClient::__call() delegates to PendingRequest src/ApiClient.php41-45
• PendingRequest::__call() delegates to ClientPendingRequest src/PendingRequest.php257-263

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

---

Configuration Execution Flow

This diagram shows how configuration is applied during request execution:

Configuration Application Sequence

Sources: src/ApiClient.php112-115 src/PendingRequest.php53-341

---

Middleware Configuration Details

Enabling/Disabling Middleware

The $enableMiddleware flag provides a master switch for all middleware processing:

• When true: Both request and response middleware pipelines execute src/PendingRequest.php274-288
• When false: Middleware pipelines are skipped entirely

This can be toggled at the client level or per-request:

Middleware Class Lists

Middleware arrays contain class names as strings. The order matters as middleware executes sequentially:

Middleware classes are instantiated with the client's configuration object src/PendingRequest.php322 and cached to avoid repeated instantiation src/PendingRequest.php318-322

Middleware Options Context

Middleware options are attached to the request context before middleware execution:

Sources: src/PendingRequest.php31-307

---

Resource Class Configuration

The resource class transforms raw HTTP responses into application-specific objects. It must extend ApiResource:

The resource class is validated when set via withResource() src/PendingRequest.php152-162 and used to transform responses src/PendingRequest.php290

Sources: src/ApiClient.php22-63 src/PendingRequest.php29-290

---

Custom Configuration Object Pattern

The $config property uses DataObject from hypervel/support to store application-specific configuration:

Example implementation:

Sources: src/ApiClient.php16-55 src/PendingRequest.php322