Making HTTP Requests

This page covers the core process of constructing and executing HTTP requests using the hypervel/http-client library. It explains the request creation flow, available HTTP methods, and the execution pipeline.

For detailed configuration options (headers, authentication, timeouts, etc.), see Request Configuration. For body formats and file uploads, see Request Body Formats. For asynchronous requests, see Asynchronous Requests. For response handling, see Response Processing.

Request Creation Flow

The HTTP client follows a fluent builder pattern where requests are created through the Factory and configured using PendingRequest methods.

Request Creation and Execution Flow

Sources: src/Factory.php404-417 src/PendingRequest.php187-210 src/PendingRequest.php1034-1038

Basic HTTP Methods

The library provides dedicated methods for all standard HTTP verbs. Each method is implemented in the PendingRequest class and ultimately calls the send() method.

HTTP Method Implementation Map

Method	Purpose	Data Parameter	Query Parameter
get()	Retrieve data	❌	✅
post()	Create resources	✅	❌
put()	Update/replace resources	✅	❌
patch()	Partial updates	✅	❌
delete()	Remove resources	✅ (optional)	❌
head()	Get headers only	❌	✅

Sources: src/PendingRequest.php628-637 src/PendingRequest.php660-665 src/PendingRequest.php684-689 src/PendingRequest.php672-677 src/PendingRequest.php696-705 src/PendingRequest.php644-653

Request Configuration Overview

The PendingRequest class provides extensive configuration through fluent methods. All configuration is accumulated in the internal $options array and applied during request execution. Configuration methods support method chaining for convenient setup.

Configuration Categories

Category	Key Methods	Details
Headers	withHeaders(), withHeader(), acceptJson()	See Request Configuration
Authentication	withBasicAuth(), withDigestAuth(), withToken()	See Request Configuration
Timeouts	timeout(), connectTimeout()	Default: 30s request, 10s connect
Redirects	maxRedirects(), withoutRedirecting()	See Request Configuration
SSL	withoutVerifying()	See Request Configuration
Body Format	asJson(), asForm(), asMultipart(), withBody()	See Request Body Formats
Advanced	withOptions(), withMiddleware(), retry()	See Advanced Features

Sources: src/PendingRequest.php93 src/PendingRequest.php195-200

Request Body Formats Overview

The PendingRequest class supports multiple body formats controlled by the bodyFormat property. The format determines how request data is encoded and sent to the server.

Supported Body Formats

Format	Method	Content-Type	Use Case
JSON	asJson()	application/json	Default format, API requests
Form	asForm()	application/x-www-form-urlencoded	Form submissions
Multipart	asMultipart()	multipart/form-data	File uploads
Raw	withBody()	Custom	Binary data, custom formats

The body format is set during configuration and applied during request execution by the parseHttpOptions() method at src/PendingRequest.php807-833 By default, all requests use JSON format as set in the constructor at src/PendingRequest.php193

For detailed information on sending each body format and working with file attachments, see Request Body Formats.

Sources: src/PendingRequest.php68 src/PendingRequest.php193 src/PendingRequest.php238-242 src/PendingRequest.php247-250 src/PendingRequest.php285-289 src/PendingRequest.php225-234

Configuration Application and Merging

When a request is executed, the PendingRequest combines multiple configuration sources in a specific order:

Configuration Merge Order

The merging is performed by the mergeOptions() method at src/PendingRequest.php1196-1202 which uses array_merge_recursive() for mergeable options (headers, cookies, query, form_params, json, multipart) and array_replace_recursive() for other options.

Sources: src/PendingRequest.php195-200 src/Factory.php416 src/PendingRequest.php513-521 src/PendingRequest.php1196-1202

Asynchronous Requests Overview

The HTTP client supports asynchronous requests that return PromiseInterface instances instead of immediate Response objects. Async mode is enabled by calling the async() method on a PendingRequest instance at src/PendingRequest.php237-242

Sync vs Async Execution Decision

When async is true, the send() method at src/PendingRequest.php713-794 calls makePromise() at src/PendingRequest.php853-885 instead of executing synchronously. The promise is resolved when the underlying Guzzle async request completes.

For detailed information on working with promises, handling concurrent requests, and managing async execution, see Asynchronous Requests.

Sources: src/PendingRequest.php150 src/PendingRequest.php237-242 src/PendingRequest.php725-727 src/PendingRequest.php853-885

Request Execution Pipeline

The request execution pipeline transforms a configured PendingRequest into an HTTP request and processes the response through multiple handler layers.

Complete Execution Pipeline

Execution Steps

1. HTTP Method Call - Methods like get(), post(), put() at src/PendingRequest.php628-705 call send() with the HTTP method and URL
2. URL Expansion - expandUrlParameters() at src/PendingRequest.php799-802 applies RFC 6570 URI template expansion
3. Options Parsing - parseHttpOptions() at src/PendingRequest.php807-833 processes body format and prepares Guzzle options
4. Client Building - buildClient() at src/PendingRequest.php1035-1038 retrieves or creates a Guzzle client with the handler stack
5. Handler Stack Construction - buildHandlerStack() at src/PendingRequest.php1059-1062 creates a HandlerStack with layered handlers
6. Request Execution - sendRequest() at src/PendingRequest.php953-972 executes the request through the handler stack

Handler Stack Layers

The pushHandlers() method at src/PendingRequest.php1067-1078 adds handlers in specific order:

Layer	Handler	Purpose	Source
1	User Middleware	Custom request/response transformation	src/PendingRequest.php1070-1072
2	Before Sending	Execute callbacks, dispatch RequestSending event	src/PendingRequest.php1083-1090
3	Recorder	Record request/response pairs for testing	src/PendingRequest.php1095-1111
4	Stub	Intercept requests for testing, return fake responses	src/PendingRequest.php1116-1147
5	Base Handler	Execute actual HTTP request via Guzzle	Guzzle default

Handlers execute in order during the request phase and in reverse order during the response phase, following Guzzle's middleware pattern.

Sources: src/PendingRequest.php713-794 src/PendingRequest.php953-972 src/PendingRequest.php1059-1078

Error Handling During Requests

The request system includes comprehensive error handling with event dispatching and exception conversion.

Sources: src/PendingRequest.php773-782 src/PendingRequest.php1277-1282 src/PendingRequest.php24 src/PendingRequest.php25 src/PendingRequest.php26