PendingRequest

The PendingRequest class serves as the central orchestrator for the Hypervel API Client, managing the complete lifecycle of HTTP requests from initial configuration through middleware execution to final response transformation. It acts as the bridge between the high-level ApiClient entry point and the low-level HTTP transport layer.

For information about the initial client setup and configuration, see ApiClient. For details on request building and PSR-7 implementation, see ApiRequest. For response handling, see ApiResponse and ApiResource. For middleware system details, see Middleware System.

Class Overview

The PendingRequest class is a generic class templated with TResource (extending ApiResource) to maintain type safety throughout the request-response lifecycle. It inherits behavior from ClientPendingRequest through a mixin pattern and includes the Conditionable trait for conditional method chaining.

Class Declaration and Template

PendingRequest<TResource of ApiResource>

The class is declared at src/PendingRequest.php18-22 with template parameter TResource that flows through to the return types of all HTTP methods.

Sources: src/PendingRequest.php18-22

Key Properties

Property	Type	Purpose
$client	ApiClient	Reference to parent client for configuration access
$resource	class-string<TResource>	Class name of the resource to instantiate
$enableMiddleware	bool	Controls middleware execution
$middlewareOptions	array	Options passed to middleware via context
$guzzleOptions	array	Guzzle HTTP client options
$requestMiddleware	array<callable|object|string>	Request middleware pipeline
$responseMiddleware	array<callable|object|string>	Response middleware pipeline
$request	?ClientPendingRequest	Cached HTTP client instance
$pipeline	Pipeline	Pipeline executor for middleware
$cachedMiddleware	static array	Middleware instance cache

Sources: src/PendingRequest.php26-51

Property Initialization

The constructor receives an ApiClient instance and optional Pipeline, copying middleware configuration and settings from the client:

Sources: src/PendingRequest.php53-62

Request Lifecycle Orchestration

The PendingRequest class orchestrates the complete request-response lifecycle, coordinating between request building, middleware execution, HTTP transport, and response transformation.

Complete Lifecycle Flow

Sources: src/PendingRequest.php265-291

The sendRequest Method

The sendRequest method at src/PendingRequest.php265-291 is the core orchestration method that:

1. Extracts method arguments using func_get_args()
2. Creates HTTP client via getClient()
3. Registers request interceptor using beforeSending callback
4. Builds ApiRequest from PSR-7 request
5. Executes request middleware if enabled
6. Performs HTTP call via delegated method
7. Wraps response in ApiResponse
8. Executes response middleware if enabled
9. Transforms to ApiResource via static factory method

Sources: src/PendingRequest.php265-291

Request Middleware Processing

The handleMiddlewareRequest method at src/PendingRequest.php293-299 processes requests through the middleware pipeline by:

• Adding middleware options to request context
• Creating middleware instances via createMiddleware
• Executing pipeline with Pipeline::send()->through()->thenReturn()

Sources: src/PendingRequest.php293-299

Response Middleware Processing

The handleMiddlewareResponse method at src/PendingRequest.php301-307 mirrors the request middleware processing for responses:

Sources: src/PendingRequest.php301-307

HTTP Method Interface

The PendingRequest class provides convenience methods for all standard HTTP verbs, each returning a typed TResource instance.

HTTP Method Summary

Method	Signature	HTTP Verb	Data Parameter
get()	get(string $url, array|JsonSerializable|string|null $query)	GET	Query parameters
head()	head(string $url, array|string|null $query)	HEAD	Query parameters
post()	post(string $url, array|JsonSerializable $data)	POST	Request body
patch()	patch(string $url, array $data)	PATCH	Request body
put()	put(string $url, array $data)	PUT	Request body
delete()	delete(string $url, array $data)	DELETE	Request body
send()	send(string $method, string $url, array $options)	Custom	Options array

Sources: src/PendingRequest.php170-244

Method Implementation Pattern

All HTTP methods follow the same implementation pattern, delegating to sendRequest:

Each method at src/PendingRequest.php170-244 calls sendRequest with the HTTP method name as the first argument, followed by the method's parameters.

Sources: src/PendingRequest.php170-244

Return Type Safety

All HTTP methods are annotated with @return TResource and return ApiResource as the concrete type, maintaining type safety through the generic template parameter:

@template TResource of ApiResource
...
@return TResource
public function get(string $url, ...): ApiResource

Sources: src/PendingRequest.php18-19 src/PendingRequest.php172-175

Middleware Management

The PendingRequest class provides comprehensive middleware management capabilities, including runtime configuration, caching, and pipeline execution.

Middleware Configuration Methods

Method	Purpose	Behavior
enableMiddleware()	Enable middleware execution	Sets $enableMiddleware = true
disableMiddleware()	Disable middleware execution	Sets $enableMiddleware = false
withMiddlewareOptions(array)	Set middleware context options	Replaces $middlewareOptions
withRequestMiddleware(array)	Replace request middleware	Replaces $requestMiddleware
withAddedRequestMiddleware(array)	Add request middleware	Merges into $requestMiddleware
withResponseMiddleware(array)	Replace response middleware	Replaces $responseMiddleware
withAddedResponseMiddleware(array)	Add response middleware	Merges into $responseMiddleware

Sources: src/PendingRequest.php64-142

Middleware Instance Creation and Caching

The createMiddleware method at src/PendingRequest.php309-326 instantiates middleware classes with built-in caching:

The implementation:

1. Validates each middleware class exists
2. Checks static cache $cachedMiddleware by class name
3. Creates new instance with $this->client->getConfig() if not cached
4. Stores instance in cache
5. Returns array of middleware instances

Sources: src/PendingRequest.php309-326

Cache Management

The static flushCache() method at src/PendingRequest.php247-252 clears the middleware instance cache:

This is useful for testing or when middleware configuration changes require fresh instances.

Sources: src/PendingRequest.php247-252

Configuration Methods

The PendingRequest class provides fluent configuration methods for customizing request behavior.

Guzzle Options Configuration

The withGuzzleOptions method at src/PendingRequest.php94-102 sets HTTP client options that are passed to the underlying Guzzle client:

The options are applied lazily when getClient() is called at src/PendingRequest.php336-338

Sources: src/PendingRequest.php94-102 src/PendingRequest.php336-338

Resource Class Configuration

The withResource method at src/PendingRequest.php145-167 allows runtime resource class changes with validation:

This validates both class existence and inheritance from ApiResource.

Sources: src/PendingRequest.php145-167

Integration Points

The PendingRequest class integrates with multiple external components to orchestrate the request lifecycle.

Component Integration Map

Sources: src/PendingRequest.php53-62 src/PendingRequest.php328-341

HTTP Client Integration

The getClient method at src/PendingRequest.php328-341 creates and caches the underlying HTTP client:

This method:

• Uses singleton pattern with $this->request cache
• Creates client via Http::throw() facade
• Applies Guzzle options if configured
• Returns ClientPendingRequest instance

Sources: src/PendingRequest.php328-341

Magic Method Delegation

The __call method at src/PendingRequest.php254-263 delegates unknown methods to the HTTP client:

This enables access to all ClientPendingRequest methods (e.g., withHeaders, withToken, asJson) without explicit method definitions. The mixin annotation @mixin ClientPendingRequest at src/PendingRequest.php20 provides IDE support.

Sources: src/PendingRequest.php20 src/PendingRequest.php254-263

Internal Implementation Details

Async Request Handling

The sendRequest method explicitly prevents async requests at src/PendingRequest.php280-282:

This ensures the API client maintains synchronous behavior, simplifying error handling and middleware execution.

Sources: src/PendingRequest.php280-282

Request Interception Pattern

The beforeSending callback at src/PendingRequest.php272-278 uses a closure with reference capture to intercept and transform requests:

The &$request reference allows the ApiRequest instance to be captured for later use in resource creation at src/PendingRequest.php290

Sources: src/PendingRequest.php272-278 src/PendingRequest.php290

Method Argument Processing

The sendRequest method uses func_get_args() and array_shift() for flexible argument handling:

This pattern allows the method to accept variable arguments that are forwarded to the underlying HTTP client method.

Sources: src/PendingRequest.php267-268

Middleware Options Context Flow

Middleware options are injected into the request/response context at src/PendingRequest.php296 and src/PendingRequest.php304 making them accessible to middleware via the HasContext trait.

Sources: src/PendingRequest.php296 src/PendingRequest.php304

Traits and Mixins

The class uses two key traits/mixins:

1. Conditionable trait src/PendingRequest.php24 - Provides when() and unless() methods for conditional fluent chaining
2. ClientPendingRequest mixin src/PendingRequest.php20 - Documents delegation pattern for IDE autocomplete

Sources: src/PendingRequest.php20 src/PendingRequest.php24