Asynchronous Requests

Overview

The PendingRequest class supports asynchronous request execution through the $async property src/PendingRequest.php150 When enabled, HTTP verb methods return GuzzleHttp\Promise\PromiseInterface instead of Response objects, enabling non-blocking concurrent operations.

The implementation uses Guzzle's requestAsync() method src/PendingRequest.php955 instead of the synchronous request() method, with promises resolved through Guzzle's promise implementation.

For request configuration that applies to both sync and async modes, see page 5.1. For body format options, see page 5.2.

Sources: src/PendingRequest.php150 src/PendingRequest.php955 src/PendingRequest.php725-727

Async Mode Control

The async() Method

The async() method src/PendingRequest.php1237-1242 toggles the $async boolean property:

Usage:

Sources: src/PendingRequest.php1237-1242

HTTP Verb Methods Return Types

All HTTP verb methods in PendingRequest have union return types supporting both execution modes:

Method	Lines	Return Type	Sync Mode Returns	Async Mode Returns
get()	628-637	PromiseInterface|Response	Response	PromiseInterface
post()	660-665	PromiseInterface|Response	Response	PromiseInterface
put()	684-689	PromiseInterface|Response	Response	PromiseInterface
patch()	672-677	PromiseInterface|Response	Response	PromiseInterface
delete()	696-705	PromiseInterface|Response	Response	PromiseInterface
head()	644-653	PromiseInterface|Response	Response	PromiseInterface

Sources: src/PendingRequest.php628-705

Request Execution Examples

Single Async Request

Concurrent Requests

Sources: src/PendingRequest.php628-637 src/PendingRequest.php725-727

Request Execution Flow

Title: Execution Path Determination in send() Method

The send() method src/PendingRequest.php713-794 routes to makePromise() src/PendingRequest.php726 when $this->async === true src/PendingRequest.php725 otherwise uses retry() wrapper for synchronous execution src/PendingRequest.php731

The sendRequest() method src/PendingRequest.php953-972 selects $clientMethod = 'requestAsync' or 'request' based on the $this->async property src/PendingRequest.php955 then invokes $client->{$clientMethod}() src/PendingRequest.php971

Sources: src/PendingRequest.php713-794 src/PendingRequest.php725-727 src/PendingRequest.php953-972

Promise Chain Construction

Title: Promise Handler Chain in makePromise() Method

The makePromise() method src/PendingRequest.php853-885 constructs a promise chain with three handlers:

1. First then() handler src/PendingRequest.php856-860 wraps ResponseInterface in Response via newResponse(), calls populateResponse(), and dispatches ResponseReceived event
2. otherwise() handler src/PendingRequest.php862-874 catches ConnectException and TransferException, converts to ConnectionException, and dispatches ConnectionFailed event
3. Final then() handler src/PendingRequest.php875-884 invokes handlePromiseResponse() for retry logic and throw callbacks

The promise is stored in $this->promise src/PendingRequest.php855 for retrieval via getPromise() src/PendingRequest.php1247-1250

Sources: src/PendingRequest.php853-885

Promise Response Processing

Title: Response Evaluation in handlePromiseResponse() Method

The handlePromiseResponse() method src/PendingRequest.php892-946 evaluates resolved promise values:

1. Successful Response objects return immediately src/PendingRequest.php899-900
2. RequestException instances are wrapped via populateResponse() src/PendingRequest.php903-905
3. $this->retryWhenCallback determines retry eligibility src/PendingRequest.php908-912
4. Retry triggers recursive makePromise() call with incremented $attempt src/PendingRequest.php928
5. $this->throwCallback and $this->throwIfCallback control exception throwing src/PendingRequest.php931-939
6. $this->retryThrow determines final exception handling src/PendingRequest.php941-942

Sources: src/PendingRequest.php892-946

Retry Logic in Async Mode

Configuration via retry() Method

The retry() method src/PendingRequest.php496-508 configures retry properties used by both execution modes:

Parameter	Property Set	Purpose
int $times	$this->tries	Number of attempts
int|Closure $sleepMilliseconds	$this->retryDelay	Delay between retries
callable $when	$this->retryWhenCallback	Condition evaluating retry eligibility
bool $throw	$this->retryThrow	Whether to throw after exhausting retries

Sources: src/PendingRequest.php496-508

Async Retry Mechanism

Title: Recursive Retry Flow via makePromise() Calls

Unlike synchronous mode which uses the retry() helper src/PendingRequest.php731 async mode implements retry through recursive makePromise() calls src/PendingRequest.php928:

• Delay calculated via value($this->retryDelay, $attempt, $exception) stored in $options['delay'] src/PendingRequest.php922-926
• $this->retryWhenCallback evaluated to determine retry eligibility src/PendingRequest.php908-912
• $potentialTries computed as is_array($this->tries) ? count($this->tries) + 1 : $this->tries src/PendingRequest.php917-919
• $attempt parameter incremented and passed to recursive makePromise() invocation src/PendingRequest.php928

Sources: src/PendingRequest.php731 src/PendingRequest.php908-928

Client Reusability

Title: Client Instance Management in buildClient() Flow

Async requests require reusable ClientInterface instances. The requestsReusableClient() method src/PendingRequest.php1043-1046 returns true when:

• $this->async === true src/PendingRequest.php1045 or
• $this->client !== null (custom client via setClient()) src/PendingRequest.php1045

The getReusableClient() method src/PendingRequest.php1051-1054 caches the client in $this->client using null coalescing assignment (??=), invoking $this->factory->getClient() with connection configuration.

Sources: src/PendingRequest.php1035-1038 src/PendingRequest.php1043-1054

Promise Retrieval

The getPromise() method src/PendingRequest.php1247-1250 returns the cached PromiseInterface stored in $this->promise:

Usage:

Returns null if no async request has been initiated.

Sources: src/PendingRequest.php1247-1250 src/PendingRequest.php155

Event Dispatching

Events dispatch within the promise chain. The same three events fire in async mode as synchronous mode:

Event Class	Dispatch Location	Method
RequestSending	Via beforeSendingCallbacks before promise creation	dispatchRequestSendingEvent()
ResponseReceived	First then() handler after response wrapping	dispatchResponseReceivedEvent()
ConnectionFailed	otherwise() handler on connection errors	dispatchConnectionFailedEvent()

Title: Event Dispatch Points in Promise Chain

The RequestSending event dispatches before promise creation via beforeSendingCallbacks src/PendingRequest.php202-209 which invokes dispatchRequestSendingEvent() src/PendingRequest.php207 The ResponseReceived and ConnectionFailed events dispatch within promise handlers src/PendingRequest.php859 src/PendingRequest.php866

Sources: src/PendingRequest.php202-209 src/PendingRequest.php856-869 src/PendingRequest.php1255-1282

Testing Support

The stub handler intercepts async requests transparently. The buildStubHandler() method src/PendingRequest.php1116-1147 checks $this->stubCallbacks and returns faked responses as promises.

Title: Stub Handler Logic in Async Mode

Example:

Factory::response() src/PendingRequest.php1136 creates PromiseInterface instances that resolve through the same handler chain as real requests.

For complete testing documentation, see page 9.

Sources: src/PendingRequest.php1116-1147

Code Entity Reference

Properties in PendingRequest

Property	Type	Line	Description
$async	bool	150	Async mode flag
$promise	?PromiseInterface	155	Cached promise instance
$client	?ClientInterface	46	Reusable client instance

Sources: src/PendingRequest.php46 src/PendingRequest.php150 src/PendingRequest.php155

Methods in PendingRequest

Method	Lines	Return Type	Function
async()	1237-1242	static	Toggle async mode
getPromise()	1247-1250	?PromiseInterface	Retrieve stored promise
makePromise()	853-885	PromiseInterface	Create promise with handlers
handlePromiseResponse()	892-946	mixed	Process resolved promise value
requestsReusableClient()	1043-1046	bool	Check reusable client requirement
getReusableClient()	1051-1054	ClientInterface	Get/create cached client
sendRequest()	953-972	PromiseInterface|ResponseInterface	Execute HTTP request

Sources: src/PendingRequest.php853-885 src/PendingRequest.php892-946 src/PendingRequest.php953-972 src/PendingRequest.php1043-1054 src/PendingRequest.php1237-1250

---

Important Considerations

Performance Implications

• Connection Pooling: Async requests benefit from connection pooling. See Connection Pooling for configuration.
• Memory Usage: Multiple pending promises consume memory. Resolve promises promptly to free resources.
• Event Loop: GuzzleHttp uses an internal event loop. Blocking operations in promise handlers can reduce performance gains.

Client Reuse

Async mode automatically creates a reusable client instance. This client is stored in the $client property and reused across requests from the same PendingRequest instance. The client is retrieved through the Factory's pooling mechanism if connection pooling is configured.

Sources: src/PendingRequest.php1043-1054

Error Handling

Exceptions in async mode are returned as values from promises rather than thrown immediately. Use promise->wait() or promise->then() error handlers to catch them:

For more on error handling strategies, see Error Handling and Exceptions.

Middleware Execution

All middleware (global, request-specific, and built-in handlers) executes within the promise chain. This includes:

• Stub handler (for fakes)
• Recorder handler (for test assertions)
• Before-sending handler (for callbacks)
• User-defined middleware

Sources: src/PendingRequest.php1059-1078

---

Summary

Asynchronous requests in the Hypervel HTTP Client provide:

1. Non-blocking execution via async() method
2. Promise-based API using GuzzleHttp's promise implementation
3. Transparent retry logic that works recursively in async mode
4. Automatic client reuse for optimal performance
5. Full middleware support including stubs for testing
6. Event dispatching within promise chains

All configuration methods (headers, authentication, body formats, etc.) work identically in both sync and async modes, with only the return type changing from Response to PromiseInterface.

Sources: src/PendingRequest.php1-1337