Response Processing

Purpose and Scope

This page provides an overview of the Response class and how HTTP responses are processed in the Hypervel HTTP Client. The Response class wraps PSR-7 ResponseInterface objects and provides a rich, developer-friendly API for accessing response data, checking status codes, handling errors, and debugging.

For detailed documentation on extracting and transforming response data (JSON decoding, collections, fluent objects), see Data Extraction and Transformation. For comprehensive coverage of status code checking methods and response validation, see Status Code Checking.

Sources: src/Response.php1-501

---

Response Class Architecture

The Response class serves as the primary interface for working with HTTP responses. It wraps a PSR-7 ResponseInterface and extends it with convenience methods, type-safe data access, and integration with the HTTP client's testing and event systems.

Sources: src/Response.php22-56

---

Response Lifecycle

The following diagram illustrates how Response objects are created and integrated into the request execution flow:

Sources: src/Response.php52-56 src/Response.php42-49

---

Core Capabilities

The Response class organizes its functionality into several distinct categories:

Capability Category	Primary Methods	Purpose	Details
Data Access & Transformation	body(), json(), object(), collect(), fluent(), resource()	Extract and transform response data into various formats	See Data Extraction and Transformation
Status Code Checking	status(), successful(), failed(), clientError(), serverError(), redirect()	Query response status and classify outcomes	See Status Code Checking
Header Access	header(), headers()	Retrieve response headers	src/Response.php155-168
Error Handling	throw(), throwIf(), throwIfStatus(), throwIfClientError(), throwIfServerError(), toException(), onError()	Convert responses to exceptions or handle errors	src/Response.php281-373
Metadata	effectiveUri(), cookies(), handlerStats(), reason()	Access request/response metadata	src/Response.php181-260
Debugging	dump(), dd(), dumpHeaders(), ddHeaders()	Inspect response data during development	src/Response.php376-431
PSR-7 Interop	toPsrResponse(), __call()	Access underlying PSR-7 response or proxy methods	src/Response.php273-500
Resource Management	close()	Close response stream and underlying resources	src/Response.php263-270

Sources: src/Response.php1-501

---

Data Caching and Custom Decoding

The Response class implements intelligent caching for JSON decoding to avoid redundant parsing:

The decoded property src/Response.php34 caches the parsed JSON response after the first call to json(), collect(), fluent(), or array access. This cache is cleared if a custom decoder is set via decodeUsing() src/Response.php106-112

Sources: src/Response.php34 src/Response.php69-80 src/Response.php106-124

---

ArrayAccess Support

The Response class implements the ArrayAccess interface src/Response.php25 allowing responses to be accessed using array syntax:

The array access implementation is read-only src/Response.php460-475 Attempting to modify response data via array syntax throws a LogicException to prevent accidental mutations of immutable response data.

Sources: src/Response.php433-475

---

PSR-7 Compatibility

The Response class maintains full compatibility with PSR-7 while extending it:

Aspect	Implementation	Notes
Wrapping	Constructor accepts ResponseInterface src/Response.php54	Stores PSR-7 response as protected property
Unwrapping	toPsrResponse() method src/Response.php273-278	Returns original PSR-7 response for interoperability
Method Proxying	__call() magic method src/Response.php495-500	Forwards undefined methods to PSR-7 response (after checking macros)
Macroable	Uses Macroable trait src/Response.php27-29	Allows runtime extension of Response class

This design allows the Response class to be used anywhere a PSR-7 response is expected, while providing enhanced functionality for common use cases.

Sources: src/Response.php22-29 src/Response.php54 src/Response.php273-278 src/Response.php495-500

---

Metadata and Statistics

Beyond the response body, the Response class provides access to request metadata:

The cookies src/Response.php44 and transferStats src/Response.php49 properties are populated by PendingRequest during response creation. The effectiveUri() method src/Response.php187-192 returns the final URI after redirects, while handlerStats() src/Response.php256-260 provides Guzzle-specific statistics about the HTTP transfer.

Sources: src/Response.php42-49 src/Response.php187-192 src/Response.php247-260

---

Error Handling Integration

The Response class provides multiple methods for error handling, from simple status checks to exception throwing:

All exception-throwing methods return the Response object (if no exception is thrown), enabling method chaining src/Response.php297-373 The throw() method accepts an optional callback that receives the response and exception before the exception is thrown src/Response.php297-310

Sources: src/Response.php281-373

---

Debugging Tools

The Response class includes methods for quick debugging during development:

Method	Purpose	Behavior
dump(?string $key = null)	Dump response content	Outputs body (auto-detects JSON), returns $this src/Response.php380-397
dd(?string $key = null)	Dump and die	Outputs body, exits with code 1 src/Response.php404-409
dumpHeaders()	Dump response headers	Outputs headers array, returns $this src/Response.php413-419
ddHeaders()	Dump headers and die	Outputs headers, exits with code 1 src/Response.php426-431

All dump methods support an optional $key parameter to dump a specific nested value using dot notation src/Response.php390-394 The methods automatically detect JSON content and pretty-print it src/Response.php384-388

Sources: src/Response.php376-431

---

Stringable Implementation

The Response class implements the Stringable interface src/Response.php25 allowing response objects to be cast to strings:

The __toString() method src/Response.php482-485 delegates to body(), making it convenient to output response content directly.

Sources: src/Response.php25 src/Response.php482-485

---

Summary

The Response class is the primary interface for working with HTTP responses in the Hypervel HTTP Client. It wraps PSR-7 ResponseInterface objects and provides:

• Rich data access through methods like json(), collect(), and fluent() (detailed in Data Extraction and Transformation)
• Comprehensive status checking via methods like successful(), failed(), and clientError() (detailed in Status Code Checking)
• Flexible error handling with exception throwing and conditional callbacks
• Developer-friendly debugging tools for inspecting response data
• Full PSR-7 compatibility while extending functionality
• Intelligent caching to optimize JSON parsing performance

The class is designed to be both powerful and easy to use, with method chaining support throughout and integration with the HTTP client's testing and event systems.

Sources: src/Response.php1-501