Request Body Formats

Purpose and Scope

This document explains how to send HTTP request bodies in different formats using the Hypervel HTTP Client. It covers the four supported body formats: JSON, form-encoded, multipart, and raw body data. Each format is appropriate for different use cases and automatically sets the corresponding Content-Type header.

For information about other request configuration options like headers, authentication, and timeouts, see Request Configuration. For details about the request execution process, see PendingRequest.

---

Overview of Body Formats

The PendingRequest class supports four distinct body formats, each managed through the internal bodyFormat property and corresponding configuration methods:

Body Format	Content-Type	Use Case	Method
json	application/json	API requests with structured data (default)	asJson()
form_params	application/x-www-form-urlencoded	Traditional HTML form submissions	asForm()
multipart	multipart/form-data	File uploads with form fields	asMultipart() or attach()
body	Custom (configurable)	Raw request bodies with custom content types	withBody()

Sources: src/PendingRequest.php68 src/PendingRequest.php175-182

---

Body Format Architecture

The following diagram illustrates how body formats are processed in the request lifecycle:

Diagram: Body Format Processing Flow

Sources: src/PendingRequest.php239-299 src/PendingRequest.php807-833

---

JSON Body Format (Default)

JSON is the default body format for all PendingRequest instances. It is automatically configured during construction and is ideal for API communication with structured data.

Configuration

The asJson() method sets the body format to json and the Content-Type header to application/json:

src/PendingRequest.php239-242

Usage with HTTP Methods

When using HTTP methods that accept data (POST, PUT, PATCH, DELETE), the data parameter is sent as JSON:

The data array is passed to Guzzle's json option, which handles JSON encoding automatically.

Initialization

The JSON body format is set by default in the PendingRequest constructor:

src/PendingRequest.php193

Sources: src/PendingRequest.php193 src/PendingRequest.php239-242 src/PendingRequest.php660-665

---

Form-Encoded Body Format

Form-encoded format is used for traditional HTML form submissions where data is sent as URL-encoded key-value pairs.

Configuration

The asForm() method switches the body format to form_params and sets the appropriate content type:

src/PendingRequest.php247-250

Usage Example

The data is passed to Guzzle's form_params option, which automatically URL-encodes the parameters.

Content Detection

The Request class can detect form-encoded requests by checking the Content-Type header:

src/Request.php168-171

Sources: src/PendingRequest.php247-250 src/Request.php168-171

---

Multipart Body Format

Multipart format is used for file uploads and mixed form data. It supports both regular form fields and file attachments.

Configuration

The multipart body format is activated either explicitly via asMultipart() or automatically when attaching files via attach():

src/PendingRequest.php286-289

File Attachment

The attach() method allows attaching files to the request:

src/PendingRequest.php257-281

The method accepts either individual file parameters or an array of files:

Multipart Data Structure

Files attached via attach() are stored in the pendingFiles array property:

src/PendingRequest.php78

During request execution, multipart data is transformed by parseMultipartBodyFormat():

src/PendingRequest.php840-846

This transformation converts simple key-value pairs into the multipart array format expected by Guzzle:

Multipart Processing Flow

Diagram: Multipart Request Assembly

Content Detection

The Request class can detect multipart requests:

src/Request.php185-189

The hasFile() method verifies if a specific file was attached:

src/Request.php111-122

Sources: src/PendingRequest.php257-281 src/PendingRequest.php78 src/PendingRequest.php840-846 src/Request.php185-189

---

Raw Body Format

The raw body format allows sending arbitrary content with a custom content type. This is useful for XML, plain text, binary data, or other custom formats.

Configuration

The withBody() method sets the body format to body and accepts the raw content:

src/PendingRequest.php225-234

The method signature is:

It accepts either a string or a PSR-7 StreamInterface for the body content.

Usage Examples

Raw Body Storage

The raw body content is stored in the pendingBody property:

src/PendingRequest.php73

During request execution, when the body format is body, the pendingBody value is used directly:

src/PendingRequest.php812-814

Sources: src/PendingRequest.php225-234 src/PendingRequest.php73 src/PendingRequest.php812-814

---

Body Format Selection Matrix

Diagram: Body Format Selection Decision Tree

---

Body Format and HTTP Methods

The body format affects how data is sent with different HTTP methods:

HTTP Method	Data Parameter	Body Format Usage
GET	Query string (ignored for body)	N/A (no body)
HEAD	Query string (ignored for body)	N/A (no body)
POST	$data array	Sent using current bodyFormat
PUT	$data array	Sent using current bodyFormat
PATCH	$data array	Sent using current bodyFormat
DELETE	$data array (optional)	Sent using current bodyFormat if provided

Implementation Details

The POST, PUT, PATCH, and DELETE methods all use the current bodyFormat property to determine how to send data:

src/PendingRequest.php660-665 - POST method src/PendingRequest.php684-689 - PUT method
src/PendingRequest.php672-677 - PATCH method src/PendingRequest.php696-705 - DELETE method

Each method passes data using the current body format:

Sources: src/PendingRequest.php660-705

---

Body Format Processing

Option Merging

Body format data is merged with other request options during request execution. The mergeableOptions array defines which options use recursive merging:

src/PendingRequest.php175-182

Notice that json, form_params, and multipart are all in the mergeable options list, allowing them to be combined with options from different sources.

Request Data Parsing

The parseHttpOptions() method processes the body format and prepares the final options for Guzzle:

src/PendingRequest.php807-833

The processing logic:

1. Checks if the current body format key exists in options
2. For multipart format, calls parseMultipartBodyFormat() to transform the data
3. For body format, uses the pendingBody property directly
4. Merges any pending files with the formatted body data
5. Converts Arrayable instances to arrays (except JsonSerializable for JSON format)

Data Access in Request Objects

The Request class provides the data() method to access the request body data, automatically detecting the format:

src/Request.php127-137

This method:

• Returns form parameters for form-encoded requests
• Returns JSON-decoded data for JSON requests
• Returns the stored data array for other formats

Sources: src/PendingRequest.php807-833 src/Request.php127-137

---

Body Format and Content-Type Headers

Each body format method sets the appropriate Content-Type header automatically through the contentType() method:

src/PendingRequest.php316-321

The header mappings are:

Body Format	Method	Content-Type
JSON	asJson()	application/json
Form	asForm()	application/x-www-form-urlencoded
Multipart	asMultipart()	Set automatically by Guzzle with boundary
Raw	withBody()	Custom (provided as parameter)

The Content-Type header can be overridden after setting the body format using contentType() or withHeaders() if needed.

Sources: src/PendingRequest.php316-321 src/PendingRequest.php239-250

---

Code Entity Relationships

Diagram: Body Format Class Relationships

Sources: src/PendingRequest.php38-299 src/Request.php14-189

---

Summary

The Hypervel HTTP Client provides four body formats to support different types of HTTP requests:

1. JSON (default): For modern API endpoints expecting structured data
2. Form-encoded: For traditional HTML form submissions
3. Multipart: For file uploads with optional form fields
4. Raw body: For custom content types like XML or binary data

The body format is set using dedicated methods (asJson(), asForm(), asMultipart(), withBody()) and automatically configures the appropriate Content-Type header. The selected format determines how data is passed to the underlying Guzzle HTTP client during request execution.

Sources: src/PendingRequest.php68-299 src/PendingRequest.php807-846