 |
VOOZH | about |
|
VOOZH | about |
This document covers the HTTP Client system for making external HTTP requests from Hypervel applications. The system provides a fluent API for building requests, automatic retry logic, connection pooling, middleware support, and comprehensive testing utilities with request faking. This is distinct from the incoming HTTP request handling covered in Request Lifecycle and Processing.
The HTTP Client is exposed through the Http facade and uses Guzzle as the underlying HTTP library, wrapping it with Laravel-style convenience methods and coroutine-safe connection pooling.
Sources: src/http-client/src/Factory.php1-527 src/support/src/Facades/Http.php1-122 src/http-client/composer.json1-44
The HTTP Client system consists of several key classes that work together to provide a complete HTTP client solution:
Sources: src/http-client/src/Factory.php31-96 src/http-client/src/PendingRequest.php38-210 src/http-client/src/Response.php25-56 src/http-client/src/Request.php14-28
Sources: src/http-client/src/PendingRequest.php713-795 src/http-client/src/Factory.php404-417 src/http-client/src/PendingRequest.php1034-1046
The Factory class serves as the main entry point for creating HTTP clients. It manages global middleware, global options, connection pooling, and request faking for tests.
| Responsibility | Method | Description |
|---|---|---|
| Client Creation | createPendingRequest() | Creates new PendingRequest with global settings |
| Global Middleware | globalMiddleware(), globalRequestMiddleware(), globalResponseMiddleware() | Apply middleware to all requests |
| Global Options | globalOptions() | Set options for all requests |
| Connection Management | registerConnection(), getClient() | Manage named connections with pooling |
| Testing Support | fake(), fakeSequence(), stubUrl() | Set up request stubbing |
| Assertion Methods | assertSent(), assertNotSent(), assertSentCount() | Verify requests in tests |
Sources: src/http-client/src/Factory.php31-96 src/http-client/src/Factory.php98-136 src/http-client/src/Factory.php404-417
The Factory supports connection pooling through the ClientPoolProxy class, which wraps Guzzle clients to enable connection reuse across coroutines:
Connections are registered and configured through the Factory:
registerConnection($name, $config) adds a connection to the poolables listsetConnectionConfig($name, $config) stores pool configuration (min, max connections, wait timeout)getClient($connection, $handlerStack, $config) returns either a pooled proxy or direct clientClientPoolProxySources: src/http-client/src/Factory.php436-476 src/http-client/src/ClientPoolProxy.php1-65 src/http-client/src/Factory.php73-88
The Factory accepts global middleware and options that apply to all requests:
Sources: src/http-client/src/Factory.php98-136 src/http-client/src/PendingRequest.php187-210 src/http-client/src/Factory.php414-417
The PendingRequest class provides a fluent interface for building HTTP requests. It uses method chaining to configure all aspects of a request before sending:
| Category | Methods | Purpose |
|---|---|---|
| Base URL | baseUrl($url) | Set base URL for relative paths |
| Body Format | asJson(), asForm(), asMultipart(), withBody() | Configure request body format |
| Headers | withHeaders(), withHeader(), accept(), acceptJson(), contentType() | Set request headers |
| Authentication | withBasicAuth(), withDigestAuth(), withToken() | Configure authentication |
| Parameters | withQueryParameters(), withUrlParameters() | Set query and URL template parameters |
| Timeouts | timeout(), connectTimeout() | Configure timeout behavior |
| Redirects | maxRedirects(), withoutRedirecting() | Control redirect handling |
| Files | attach() | Attach files for multipart requests |
| Options | withOptions(), withoutVerifying(), sink() | Advanced Guzzle options |
Sources: src/http-client/src/PendingRequest.php212-521 src/http-client/src/PendingRequest.php38-183
PendingRequest provides convenience methods for each HTTP verb:
All methods return either a Response object (sync) or PromiseInterface (async).
Sources: src/http-client/src/PendingRequest.php624-705 tests/HttpClient/HttpClientTest.php76-186
Sources: src/http-client/src/PendingRequest.php713-795 src/http-client/src/PendingRequest.php800-847
PendingRequest supports URL template parameters using RFC 6570 URI templates via withUrlParameters():
The expansion happens in expandUrlParameters() using GuzzleHttp\UriTemplate\UriTemplate.
Sources: src/http-client/src/PendingRequest.php410-417 src/http-client/src/PendingRequest.php800-803 tests/HttpClient/HttpClientTest.php1130-1142
The Response class wraps Guzzle's PSR-7 response with convenient methods for accessing and testing response data:
Sources: src/http-client/src/Response.php25-56 src/http-client/src/Response.php58-152 src/http-client/src/Response.php195-233
The Response class provides multiple ways to access the response body:
| Method | Return Type | Description |
|---|---|---|
body() | string | Raw response body as string |
json($key, $default) | mixed | JSON decoded as array, with dot notation key access |
object() | object|array|null | JSON decoded as object |
collect($key) | Collection | JSON as Collection, with optional key |
fluent($key) | Fluent | JSON as Fluent object |
resource() | resource | Body as PHP stream resource |
decodeUsing($callback) | self | Set custom decoder for non-JSON responses |
Sources: src/http-client/src/Response.php58-152 tests/HttpClient/HttpClientTest.php347-454
Response provides expressive status checking methods:
Sources: src/http-client/src/Response.php195-233 src/http-client/src/Concerns/DeterminesStatusCode.php (trait), tests/HttpClient/HttpClientTest.php100-334
Response supports throwing exceptions on errors:
Sources: src/http-client/src/Response.php293-373 src/http-client/src/PendingRequest.php564-592 tests/HttpClient/HttpClientTest.php1467-1545
PendingRequest supports automatic retries with customizable logic:
Sources: src/http-client/src/PendingRequest.php731-794 src/http-client/src/PendingRequest.php496-508
The retry() method configures retry behavior:
Usage Examples:
Sources: src/http-client/src/PendingRequest.php496-508 tests/HttpClient/HttpClientTest.php1547-1646
The retry mechanism uses several instance variables:
| Variable | Type | Default | Purpose |
|---|---|---|---|
$tries | array|int | 1 | Number of attempts or array of delays |
$retryDelay | Closure|int | 100 | Milliseconds to wait or callback returning delay |
$retryWhenCallback | callable|null | null | Determines if retry should happen |
$retryThrow | bool | true | Whether to throw exception after all retries |
Sources: src/http-client/src/PendingRequest.php106-118 src/http-client/src/PendingRequest.php731-794
The HTTP Client supports three types of middleware at different scopes:
Sources: src/http-client/src/Factory.php98-136 src/http-client/src/PendingRequest.php523-551 src/http-client/src/PendingRequest.php1048-1165
The buildHandlerStack() method constructs the Guzzle middleware stack:
Middleware execution order (bottom to top):
withMiddleware())Sources: src/http-client/src/PendingRequest.php1048-1075 src/http-client/src/PendingRequest.php1077-1165
Before-sending callbacks execute just before the request is sent, allowing last-minute modifications:
The default before-sending callback stores the request and cookies on the PendingRequest instance for later access.
Sources: src/http-client/src/PendingRequest.php554-561 src/http-client/src/PendingRequest.php202-209
Sources: src/http-client/src/PendingRequest.php523-551 tests/HttpClient/HttpClientTest.php1712-1850
The HTTP Client provides comprehensive testing support through request faking and stubbing:
Sources: src/http-client/src/Factory.php183-224 src/http-client/src/PendingRequest.php1136-1165 src/http-client/src/Factory.php289-306
| Method | Purpose | Example |
|---|---|---|
fake() | Stub all requests with 200 OK | Http::fake(); |
fake($callback) | Stub with callback | Http::fake(fn($req) => Http::response(['ok' => true])); |
fake($array) | Stub specific URLs | Http::fake(['github.com/*' => ['data' => 'stub']]); |
fakeSequence($url) | Create response sequence | Http::fakeSequence()->push('First')->push('Second'); |
stubUrl($url, $response) | Stub specific URL | Http::stubUrl('api.com/*', Http::response(['ok' => true])); |
Sources: src/http-client/src/Factory.php183-260 tests/HttpClient/HttpClientTest.php76-97
The Factory provides static methods for creating stubbed responses:
Sources: src/http-client/src/Factory.php139-170 src/http-client/src/ResponseSequence.php34-84 tests/HttpClient/HttpClientTest.php859-932
ResponseSequence allows defining multiple responses that will be returned in order:
By default, sequences throw OutOfBoundsException when exhausted unless dontFailWhenEmpty() is called.
Sources: src/http-client/src/ResponseSequence.php1-133 tests/HttpClient/HttpClientTest.php859-932
After faking requests, use assertion methods to verify behavior:
Sources: src/http-client/src/Factory.php308-382 tests/HttpClient/HttpClientTest.php688-743
In tests, you can ensure all requests are faked:
This prevents accidental real HTTP requests during testing.
Sources: src/http-client/src/Factory.php262-286 src/http-client/src/PendingRequest.php1136-1165 tests/HttpClient/HttpClientTest.php1874-1924
The Request object provides access to request details in assertions:
| Property/Method | Description |
|---|---|
url() | Full request URL |
method() | HTTP method (GET, POST, etc.) |
headers() | All headers as array |
hasHeader($key, $value) | Check if header exists |
body() | Raw request body |
data() | Parsed data (form or JSON) |
isJson() | Check if JSON request |
isForm() | Check if form request |
isMultipart() | Check if multipart request |
hasFile($name, $value, $filename) | Check if file attached |
$request['key'] | Array access to data |
Sources: src/http-client/src/Request.php14-279 tests/HttpClient/HttpClientTest.php524-815
Named connections can be configured with pooling parameters:
Sources: src/http-client/src/Factory.php436-444 src/http-client/src/PendingRequest.php1249-1265
Requests can be made asynchronously using async():
Sources: src/http-client/src/PendingRequest.php1219-1226 src/http-client/src/PendingRequest.php854-886
PendingRequest provides debugging methods:
These use Symfony VarDumper to output request and option details.
Sources: src/http-client/src/PendingRequest.php594-621
Sources: src/http-client/src/PendingRequest.php420-429 src/http-client/src/Response.php246-252
Response objects have access to transfer statistics:
Sources: src/http-client/src/Response.php186-260 src/http-client/src/PendingRequest.php959-965
Sources: tests/HttpClient/HttpClientTest.php76-1047 tests/HttpClient/HttpClientTest.php1547-1850
Refresh this wiki