Data Extraction and Transformation

This page documents the methods available on the Response class for extracting and transforming HTTP response data into various formats. The Response class provides multiple ways to access the response body, including raw string access, JSON decoding, collection wrappers, and fluent object notation.

For information about checking response status codes and validation, see Status Code Checking. For information about error handling and exceptions, see Error Handling and Exceptions.

Overview of Data Access Methods

The Response class wraps a PSR-7 ResponseInterface and provides a rich API for data extraction. The class supports multiple transformation formats to suit different use cases.

Response Data Extraction Methods

Method	Return Type	Purpose
body()	string	Get raw response body as string
json(?string $key, mixed $default)	mixed	Decode JSON and optionally extract nested value
object()	array|object|null	Decode JSON as object(s) instead of arrays
collect(?string $key)	Collection	Wrap decoded JSON in Collection instance
fluent(?string $key)	Fluent	Wrap decoded JSON in Fluent instance
resource()	resource	Get response body as PHP stream resource
header(string $header)	string	Get specific header value
headers()	array	Get all response headers

Sources: src/Response.php61-168

Response Data Flow

Sources: src/Response.php54-153

Raw Body Access

The body() method returns the raw response body as a string. This is the foundation for all other data extraction methods.

The Response class also implements Stringable, allowing the response to be cast to a string, which calls body() internally.

Key Methods:

• body() src/Response.php61-64 - Returns complete response body as string
• __toString() src/Response.php482-485 - Enables string casting via (string) $response

The body is retrieved from the underlying PSR-7 response's body stream by casting it to a string.

Sources: src/Response.php61-64 src/Response.php482-485

JSON Decoding

The Response class provides comprehensive JSON decoding capabilities with support for nested data access and custom decoders.

Basic JSON Decoding

The json() method decodes the response body and optionally extracts a nested value using dot notation. If no key is provided, the entire decoded array is returned.

Parameters:

• $key - Optional dot-notation path to nested value (e.g., "data.users.0.name")
• $default - Default value returned if key doesn't exist

Behavior:

• Decoded JSON is cached in the $decoded property src/Response.php34
• Uses json_decode() with associative array mode by default
• Supports dot notation for nested access via data_get() helper src/Response.php79

Sources: src/Response.php69-80

Object Decoding

The object() method decodes JSON into objects instead of associative arrays. This is useful when you prefer object property access syntax.

Behavior:

• Passes true as second parameter to decode() src/Response.php96
• Returns objects with properties accessible via -> syntax
• If response is JSON array, returns array of objects
• Does not cache the result (calls decode() directly each time)

Sources: src/Response.php94-97

JSON Decoding Flow

Sources: src/Response.php69-124

Custom Decode Callbacks

The decodeUsing() method allows you to provide a custom decoder for response bodies. This is useful for non-JSON responses or custom decoding logic.

Callback Signature:

Parameters:

• $body - Raw response body string
• $asObject - true when called from object(), false when called from json()

Behavior:

• Clears any cached decoded data src/Response.php109
• Subsequent calls to json() or object() use the custom decoder
• Pass null to reset to default JSON decoder

Use Cases:

• XML response parsing
• Custom JSON transformations
• Binary format decoding
• Response body preprocessing

Sources: src/Response.php106-124

Collections and Fluent Objects

The Response class integrates with hypervel/support package classes to provide convenient wrappers around decoded data.

Collection Wrapper

The collect() method wraps the decoded JSON in a Collection instance from the Hypervel\Support\Collection class. Collections provide array manipulation methods like map(), filter(), pluck(), etc.

Behavior:

• Calls json($key) internally to get decoded data src/Response.php131
• Returns new Collection instance wrapping the data
• Supports optional key parameter for nested access

Sources: src/Response.php129-132

Fluent Object Wrapper

The fluent() method wraps the decoded JSON in a Fluent instance from the Hypervel\Support\Fluent class. Fluent objects provide dynamic property access to array data.

Behavior:

• Calls json($key) and casts to array src/Response.php139
• Returns new Fluent instance wrapping the data
• Allows accessing array keys as object properties

Sources: src/Response.php137-140

Collection and Fluent Integration

Sources: src/Response.php129-140

Array Access Interface

The Response class implements ArrayAccess, allowing you to access decoded JSON data using array syntax.

Implementation Details:

Method	Behavior	Line Reference
offsetExists($offset)	Check if key exists in decoded JSON	src/Response.php438-441
offsetGet($offset)	Get value from decoded JSON	src/Response.php448-451
offsetSet($offset, $value)	Throws LogicException (read-only)	src/Response.php460-463
offsetUnset($offset)	Throws LogicException (read-only)	src/Response.php472-475

Important Characteristics:

• Array access is read-only - attempts to modify throw LogicException
• Delegates to json() method internally
• Only provides top-level key access (does not support nested dot notation)
• Automatically decodes JSON on first access

Sources: src/Response.php438-475

Stream Resource Access

For handling large response bodies or streaming data, the resource() method provides access to the underlying PSR-7 stream as a PHP resource.

Behavior:

• Uses GuzzleHttp\Psr7\StreamWrapper::getResource() src/Response.php151
• Returns native PHP stream resource
• Suitable for large files to avoid loading entire response into memory

Use Cases:

• Downloading large files
• Streaming response to another destination
• Processing large responses incrementally
• Integrating with APIs that accept PHP streams

Sources: src/Response.php149-152

Header Access

The Response class provides methods to access HTTP response headers.

Methods:

• header($name) src/Response.php157-160 - Returns specific header value as string
• headers() src/Response.php165-168 - Returns all headers as associative array

Behavior:

• header() delegates to PSR-7 getHeaderLine() method
• headers() delegates to PSR-7 getHeaders() method
• Header names are case-insensitive per HTTP specification

Sources: src/Response.php157-168

Debugging Utilities

The Response class provides convenience methods for debugging response data during development.

Content Dumping

Behavior:

• dump() src/Response.php380-397 - Dumps content and returns response for chaining
• dd() src/Response.php404-409 - Dumps content and exits script (dump and die)
• Automatically detects and pretty-prints JSON responses
• Supports optional key parameter to dump specific nested value

Header Dumping

Behavior:

• dumpHeaders() src/Response.php414-419 - Dumps headers and returns response
• ddHeaders() src/Response.php426-431 - Dumps headers and exits script

Sources: src/Response.php380-431

Method Reference Summary

Sources: src/Response.php1-501