Response Handling

This document covers how to work with API responses after they have been received from the target API. It explains the ApiResponse and ApiResource classes, which provide structured access to response data through multiple interfaces including array access, object properties, and method calls.

For information about making requests, see Making Requests. For architectural details about the response classes themselves, see ApiResponse and ApiResource.

---

Response Flow Overview

When a request is executed via PendingRequest, the raw HTTP response from hypervel/http-client is wrapped in an ApiResponse object, processed through any response middleware, and finally transformed into an ApiResource instance that is returned to the application.

Response Transformation Pipeline

The ApiResource serves as the primary interface for accessing response data, wrapping both the ApiResponse and the original ApiRequest for reference.

Sources: src/ApiResource.php18-29 High-Level System Architecture diagrams

---

ApiResource Structure

The ApiResource class is the main container returned to application code. It implements multiple interfaces to provide flexible data access patterns:

The resource wraps two core objects accessible via accessor methods:

Method	Return Type	Purpose
getResponse()	ApiResponse	Access the wrapped response object
getRequest()	ApiRequest	Access the original request object

Sources: src/ApiResource.php15-29 src/ApiResource.php74-82

---

Accessing Response Data

The ApiResource provides multiple patterns for accessing response data, all of which delegate to the underlying ApiResponse object.

Array Access Pattern

The ApiResource implements ArrayAccess, allowing array-style data retrieval:

The array access methods delegate directly to the ApiResponse:

Method	Implementation	Line Reference
offsetExists($offset)	$this->response->offsetExists($offset)	src/ApiResource.php119-122
offsetGet($offset)	$this->response->offsetGet($offset)	src/ApiResource.php127-130
offsetSet($offset, $value)	$this->response->offsetSet($offset, $value)	src/ApiResource.php135-138
offsetUnset($offset)	$this->response->offsetUnset($offset)	src/ApiResource.php143-146

Object Property Access

Magic methods enable property-style access to response data:

Magic Method	Behavior	Line Reference
__get($key)	Returns $this->response->offsetGet($key)	src/ApiResource.php55-58
__isset($key)	Checks isset($this->response->json()[$key])	src/ApiResource.php39-42
__unset($key)	Calls $this->response->offsetUnset($key)	src/ApiResource.php47-50

Method Call Delegation

The ApiResource uses the ForwardsCalls trait to proxy method calls to the underlying ApiResponse:

This delegation allows calling any method available on ApiResponse directly on the resource. If the method does not exist on ApiResponse, a BadMethodCallException is thrown src/ApiResource.php63-72

Sources: src/ApiResource.php39-72 src/ApiResource.php117-146

---

Response Transformation

The ApiResource provides multiple transformation methods for converting response data into different formats:

Transformation Methods

Method	Return Type	Interface	Implementation	Line Reference
toArray()	array	Arrayable	Returns $this->response->json()	src/ApiResource.php103-106
jsonSerialize()	mixed	JsonSerializable	Returns $this->resolve()	src/ApiResource.php111-114
resolve()	array	-	Returns $this->toArray()	src/ApiResource.php95-98
__toString()	string	Stringable	Returns $this->response->body()	src/ApiResource.php31-34

Transformation Flow

All transformation methods ultimately delegate to methods on the wrapped ApiResponse object:

• String conversion retrieves the raw response body
• Array/JSON conversion retrieves the parsed JSON data

Sources: src/ApiResource.php31-34 src/ApiResource.php95-114

---

Accessing Underlying Objects

While ApiResource provides convenient access patterns, you can retrieve the wrapped objects directly when needed:

Response and Request Accessors

Accessor Method	Return Type	Purpose	Line Reference
getResponse()	ApiResponse	Access full response object with all PSR-7 methods and context	src/ApiResource.php74-77
getRequest()	ApiRequest	Access original request for reference or inspection	src/ApiResource.php79-82

These accessors are useful when you need to:

• Access PSR-7 response methods (status code, headers, protocol version)
• Inspect the original request details
• Access context data via the HasContext trait on ApiResponse
• Modify response headers or body via ApiResponse mutation methods

Sources: src/ApiResource.php74-82

---

Response Mutability

The ApiResponse class extends HttpClientResponse and provides mutable methods for modifying response properties. While PSR-7 responses are typically immutable, ApiResponse updates the internal $response property to support modifications:

Mutable Response Methods

Method	Purpose	Returns	Line Reference
withStatus(int $code, string $reasonPhrase = '')	Set HTTP status code	static	src/ApiResponse.php14-20
withProtocolVersion(string $version)	Set HTTP protocol version	static	src/ApiResponse.php22-28
hasHeader(string $name)	Check if header exists	bool	src/ApiResponse.php30-34
withHeader(string $name, mixed $value)	Set/replace header	static	src/ApiResponse.php36-42
withAddedHeader(string $name, mixed $value)	Add header value	static	src/ApiResponse.php44-50
withoutHeader(string $name)	Remove header	static	src/ApiResponse.php52-58
withBody(StreamInterface $body)	Replace response body	static	src/ApiResponse.php60-66

Each mutation method:

1. Calls toPsrResponse() to get the underlying PSR-7 response
2. Invokes the corresponding PSR-7 with*() method
3. Updates the internal $response property
4. Returns $this for method chaining

Sources: src/ApiResponse.php14-66

---

Context Data Access

Both ApiResponse and, by delegation, ApiResource support context data management through the HasContext trait. Context provides a way to attach metadata that persists through the response lifecycle.

The context system is documented in detail in Context Management. When working with responses, context can be accessed via:

• $resource->getResponse()->context($key) - retrieve context data
• $resource->getResponse()->withContext($key, $value) - set context data

Sources: src/ApiResponse.php12

---

Type Safety and Generics

The response handling system maintains type safety through generic type parameters that flow from ApiClient through PendingRequest to the final ApiResource:

Generic Type Flow

Component	Generic Parameters	Purpose
ApiClient<TConfig, TResource>	TConfig: Configuration object type TResource: Resource class to instantiate	Defines the resource type returned by all requests
PendingRequest<TResource>	TResource: Resource class to instantiate	Ensures type safety in method return types

The type parameter ensures that IDEs and static analysis tools can provide accurate type information for response objects throughout the request lifecycle. The actual resource instantiation occurs via src/ApiResource.php87-90 using the static make() factory method.

Sources: High-Level System Architecture diagrams (Diagram 4), src/ApiResource.php87-90