ApiResponse

Purpose and Scope

The ApiResponse class is a mutable wrapper around PSR-7 compliant HTTP responses. It provides fluent interface methods for modifying response attributes (status code, headers, body, protocol version) while maintaining PSR-7 compatibility. This class serves as the response container that flows through the response middleware pipeline and is ultimately wrapped in an ApiResource for consumption by application code.

For information about request building, see ApiRequest. For details on how responses are transformed into consumable resources, see ApiResource. For response middleware processing, see Response Middleware.

Sources: src/ApiResponse.php1-67

---

Class Overview

ApiResponse extends HttpClientResponse from the hypervel/http-client package and implements the HasContext trait. The class provides methods to mutate response properties in a fluent manner, which is useful during response middleware processing.

Sources: src/ApiResponse.php10-12

---

Inheritance Structure

The inheritance chain establishes PSR-7 compliance while adding mutability:

Layer	Class/Interface	Purpose
Standard	Psr\Http\Message\ResponseInterface	PSR-7 HTTP response standard
Base	Hypervel\HttpClient\Response	Base response implementation from http-client
Wrapper	Hypervel\ApiClient\ApiResponse	Mutable wrapper with context support

The ApiResponse class inherits the toPsrResponse() method from HttpClientResponse, which returns the underlying PSR-7 ResponseInterface instance. All mutation methods use this to obtain the current response state, apply modifications, and store the result back.

Sources: src/ApiResponse.php10

---

Mutable Response Methods

Unlike standard PSR-7 responses which are immutable, ApiResponse provides mutable methods that return static and modify the underlying response instance. This design allows middleware to modify responses in place.

Status Modification

The withStatus() method modifies the HTTP status code and optional reason phrase:

Method Signature:

Sources: src/ApiResponse.php14-20

Protocol Version Modification

The withProtocolVersion() method changes the HTTP protocol version:

Sources: src/ApiResponse.php22-28

Header Manipulation

The class provides four methods for header management:

Method	Parameters	Purpose
hasHeader()	string $name	Check if header exists (returns bool)
withHeader()	string $name, mixed $value	Set/replace header value
withAddedHeader()	string $name, mixed $value	Add value to existing header
withoutHeader()	string $name	Remove header completely

All header modification methods follow the same pattern: retrieve the PSR-7 response via toPsrResponse(), apply the modification, store the result, and return $this for chaining.

Sources: src/ApiResponse.php30-58

Body Modification

The withBody() method replaces the response body with a new StreamInterface:

This is useful when middleware needs to transform response content (e.g., encrypting, compressing, or filtering data).

Sources: src/ApiResponse.php60-66

---

Integration with Request Lifecycle

ApiResponse plays a specific role in the request execution flow, positioned between HTTP client execution and final resource creation:

The PendingRequest class creates an ApiResponse instance after receiving the HTTP response, then passes it through the response middleware pipeline before wrapping it in an ApiResource.

Sources: src/ApiResponse.php1-67

---

Mutation Pattern

All mutation methods in ApiResponse follow a consistent pattern:

1. Call toPsrResponse() to obtain the current PSR-7 response
2. Call the corresponding PSR-7 method (which returns a new immutable instance)
3. Store the new instance in $this->response
4. Return $this for method chaining

This pattern bridges the gap between PSR-7's immutability and the need for in-place modifications during middleware processing:

Example Usage in Middleware:

Sources: src/ApiResponse.php14-66

---

Context Management

ApiResponse uses the HasContext trait to support contextual data management. This allows metadata to be attached to responses that can be accessed later in the processing pipeline or by application code.

The context system provides:

• withContext(string $key, mixed $value): static - Add context data
• context(?string $key = null): mixed - Retrieve context data

Context is particularly useful for:

• Passing metadata from middleware to application code
• Storing diagnostic information (e.g., timing, cache status)
• Tracking response transformations applied by middleware

For detailed information about context management, see HasContext Trait.

Sources: src/ApiResponse.php12

---

Method Reference Table

Method	Return Type	Mutates Instance	Purpose
withStatus(int $code, string $reasonPhrase = '')	static	Yes	Change HTTP status code
withProtocolVersion(string $version)	static	Yes	Change HTTP protocol version
hasHeader(string $name)	bool	No	Check if header exists
withHeader(string $name, mixed $value)	static	Yes	Set/replace header
withAddedHeader(string $name, mixed $value)	static	Yes	Add header value
withoutHeader(string $name)	static	Yes	Remove header
withBody(StreamInterface $body)	static	Yes	Replace response body
withContext(string $key, mixed $value)	static	Yes	Add context data (from trait)
context(?string $key = null)	mixed	No	Retrieve context data (from trait)

All mutation methods return static to enable fluent method chaining.

Sources: src/ApiResponse.php14-66

---

Usage in Middleware

Response middleware receives ApiResponse instances and can modify them before they reach the application:

Middleware can access all mutation methods to transform responses according to application requirements. The fluent interface allows chaining multiple modifications.

Sources: src/ApiResponse.php1-67