Request Body and Serialization

This page documents how to send data in API requests using the hypervel/api-client package. It covers methods for adding request data, selecting content types, and the automatic serialization process that converts data into properly formatted request bodies.

For information about configuring other aspects of requests such as headers and authentication, see Headers and Authentication. For details on HTTP methods and URL construction, see HTTP Methods and Request Configuration.

---

Purpose and Scope

The API client provides a fluent interface for constructing request bodies with automatic serialization based on content type. The system supports three primary modes:

1. JSON serialization - Default for most requests
2. Form encoding - For application/x-www-form-urlencoded submissions
3. Raw body - Direct string content for custom formats

All request body configuration occurs through the ApiRequest class, which handles data accumulation and deferred serialization.

Sources: src/ApiRequest.php1-241

---

Adding Request Data

The withData() Method

The withData() method adds data to the request body. Data is accumulated in an internal array and merged with any existing data. Serialization is deferred until the request is finalized.

Key characteristics:

Property	Behavior
Data Merging	New data is merged with existing data using array_merge()
Serialization	Deferred until toPsrRequest() is called
Flag Setting	Sets $dataChanged = true to trigger serialization
Return Value	Returns static for method chaining

Implementation: src/ApiRequest.php193-199

The method merges new data with existing data and sets the $dataChanged flag to indicate that serialization is required before the request is sent.

The withBody() Method

The withBody() method sets the request body directly as a string, bypassing the automatic serialization system. This is useful for custom content types or pre-formatted data.

Important: Calling withBody() sets $dataChanged = false, preventing automatic serialization from overwriting the custom body content.

Implementation: src/ApiRequest.php182-188

The withoutData() Method

The withoutData() method removes specific keys from the request data array before serialization.

Implementation: src/ApiRequest.php204-212

Sources: src/ApiRequest.php182-212

---

Content Type Selection

The asForm() Method

The asForm() method configures the request to send data as application/x-www-form-urlencoded. This triggers URL-encoded serialization during request finalization.

Behavior:

Implementation: src/ApiRequest.php78-89

The method checks if data conversion is needed when switching from JSON to form encoding, ensuring data integrity during content type transitions.

The asJson() Method

The asJson() method configures the request to send data as application/json. This triggers JSON encoding during request finalization.

Behavior:

Implementation: src/ApiRequest.php94-105

Similar to asForm(), this method handles data conversion when switching from form encoding to JSON.

The contentType() Method

The contentType() method sets an arbitrary Content-Type header, allowing custom content types beyond the standard form and JSON options.

Implementation: src/ApiRequest.php68-73

Sources: src/ApiRequest.php68-105

---

Automatic Serialization Process

The dataChanged Flag

The $dataChanged property tracks whether request data has been modified since the last serialization. This flag determines whether serialization needs to occur when the request is finalized.

Action	Sets dataChanged
withData()	true
asForm() (when converting)	true
asJson() (when converting)	true
withBody()	false
applyChangedData()	false (after serialization)

Declaration: src/ApiRequest.php19

The Serialization Pipeline

When toPsrRequest() is called to obtain the PSR-7 request object, the system checks the dataChanged flag and triggers serialization if needed.

Implementation: src/ApiRequest.php217-224

The applyChangedData() Method

The applyChangedData() method performs the actual serialization based on the current content type:

Serialization Logic:

Implementation: src/ApiRequest.php226-240

Key Points:

1. Form Encoding - Uses http_build_query() with & separator for application/x-www-form-urlencoded
2. JSON Encoding - Uses json_encode() for application/json or when no content type is set (JSON is default)
3. Raw Data - For other content types, data is used as-is (assumes string)
4. Stream Creation - Serialized data is wrapped in a Stream object from hyperf/engine
5. Flag Reset - $dataChanged is reset to false after serialization

Sources: src/ApiRequest.php217-240

---

Content Type Detection Methods

The ApiRequest class includes internal methods for detecting the current content type, which are used by asForm() and asJson() to handle data conversion:

Method	Detection Logic	Inherited From
isForm()	Checks if Content-Type is application/x-www-form-urlencoded	HttpClientRequest
isJson()	Checks if Content-Type is application/json	HttpClientRequest
hasHeader()	Checks if a header exists	HttpClientRequest

These methods are inherited from the base HttpClientRequest class in the hypervel/http-client package.

Sources: src/ApiRequest.php12

---

Complete Data Flow Diagram

The following diagram shows the complete flow of request data from initial configuration through serialization to final PSR-7 request:

Sources: src/ApiRequest.php1-241

---

Common Usage Patterns

Sending JSON Data (Default)

JSON is the default content type when no explicit type is set:

The second parameter of HTTP method calls is automatically passed to withData().

Sending Form-Encoded Data

Explicitly set form encoding for traditional HTML form submissions:

Sending Raw XML or Other Formats

Use withBody() for custom content types:

Building Data Incrementally

Chain multiple withData() calls to build the request body:

Removing Data Keys

Use withoutData() to remove specific keys before sending:

Sources: src/ApiRequest.php78-105 src/ApiRequest.php193-212

---

Method Reference Table

Method	Purpose	Content-Type Impact	Sets dataChanged
withData(array $data)	Add data to request body	None	Yes
withBody(string $body)	Set raw body content	None	No
withoutData(array $keys)	Remove data keys	None	No
asForm()	Set form encoding	application/x-www-form-urlencoded	Conditional
asJson()	Set JSON encoding	application/json	Conditional
contentType(string $type)	Set custom content type	Custom	No
toPsrRequest()	Finalize request	N/A - triggers serialization	N/A

Sources: src/ApiRequest.php68-224

---

Integration with PendingRequest

The PendingRequest class uses these serialization methods internally when HTTP method shortcuts are called. The second parameter of methods like get(), post(), etc. is automatically passed to withData():

This integration is covered in detail in PendingRequest and HTTP Methods.

Sources: src/ApiRequest.php193-199