Response

Purpose and Scope

The Response class wraps PSR-7 ResponseInterface objects and provides convenient methods for processing HTTP responses. It offers rich JSON decoding capabilities, semantic status code checking, error handling utilities, and debugging tools. This page documents the Response class methods and features for working with HTTP response data.

For information about making requests that produce responses, see PendingRequest. For details on response-related events, see Event System. For error handling strategies, see Error Handling and Exceptions.

Sources: src/Response.php1-501

---

Class Overview

The Response class is located at src/Response.php and serves as the primary interface for processing HTTP responses returned by the HTTP client.

Response Class Structure

Sources: src/Response.php25-29 src/Response.php54-56

---

Response Data Access

The Response class provides multiple methods for accessing the response body in different formats.

Data Access Methods Hierarchy

Sources: src/Response.php61-152

Body Access

Method	Return Type	Description	Line Reference
body()	string	Returns the full response body as a string	src/Response.php61-64
resource()	resource	Returns the response body as a PHP stream resource	src/Response.php149-152
__toString()	string	Allows the response to be cast to a string	src/Response.php482-485

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

JSON Decoding

Method	Return Type	Description	Line Reference
json(?string $key, mixed $default)	mixed	Decodes JSON body as an array; supports dot notation key access	src/Response.php69-80
object()	array|object|null	Decodes JSON body as objects instead of associative arrays	src/Response.php94-97
collect(?string $key)	Collection	Returns JSON data as a Collection instance	src/Response.php129-132
fluent(?string $key)	Fluent	Returns JSON data as a Fluent object for property access	src/Response.php137-140

The json() method caches decoded data in the $decoded property src/Response.php34 Subsequent calls use the cached version unless a custom decoder is set.

Sources: src/Response.php34 src/Response.php69-80 src/Response.php94-97 src/Response.php129-132 src/Response.php137-140

Custom JSON Decoder

The decodeUsing() method allows setting a custom JSON decoder:

Method	Parameters	Description	Line Reference
decodeUsing(?Closure $callback)	Closure(string $body, bool $asObject)	Sets a custom decoder callback; clears cached decoded data	src/Response.php106-112

The custom decoder receives two parameters:

• string $body: The raw response body
• bool $asObject: When true, should return objects instead of arrays

Sources: src/Response.php38-39 src/Response.php106-112 src/Response.php117-124

Array Access

The Response class implements ArrayAccess, allowing JSON data to be accessed using array syntax:

Method	Purpose	Line Reference
offsetExists($offset)	Checks if a key exists in decoded JSON	src/Response.php438-441
offsetGet($offset)	Retrieves 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

Sources: src/Response.php438-475

---

Headers and Metadata

The Response class provides access to response headers and metadata.

Header and Metadata Methods

Sources: src/Response.php156-260

Method	Return Type	Description	Line Reference
header(string $header)	string	Returns a single header value	src/Response.php157-160
headers()	array	Returns all headers as an associative array	src/Response.php165-168
status()	int	Returns the HTTP status code	src/Response.php173-176
reason()	string	Returns the HTTP reason phrase (e.g., "OK", "Not Found")	src/Response.php181-184
effectiveUri()	?UriInterface	Returns the effective URI after redirects	src/Response.php189-192
cookies()	CookieJar	Returns the response cookies	src/Response.php249-252
handlerStats()	array	Returns handler-specific statistics from the transfer	src/Response.php257-260

Sources: src/Response.php42-49 src/Response.php157-192 src/Response.php249-260

---

Status Code Checking

The Response class uses the DeterminesStatusCode trait to provide semantic status code checking methods.

Status Code Method Categories

Sources: src/Response.php196-233 src/Concerns/DeterminesStatusCode.php1-144

General Status Check Methods

Method	Returns true when	Line Reference
successful()	Status code is 200-299	src/Response.php197-200
redirect()	Status code is 300-399	src/Response.php205-208
failed()	Status code is 400+ (client or server error)	src/Response.php213-216
clientError()	Status code is 400-499	src/Response.php221-224
serverError()	Status code is 500+	src/Response.php229-232

Sources: src/Response.php197-232

Specific Status Code Methods

The DeterminesStatusCode trait provides methods for checking specific HTTP status codes:

Method	Status Code	Line Reference
ok()	200 OK	src/Concerns/DeterminesStatusCode.php12-15
created()	201 Created	src/Concerns/DeterminesStatusCode.php20-23
accepted()	202 Accepted	src/Concerns/DeterminesStatusCode.php28-31
noContent(int $status = 204)	204 No Content (and empty body)	src/Concerns/DeterminesStatusCode.php36-39
movedPermanently()	301 Moved Permanently	src/Concerns/DeterminesStatusCode.php44-47
found()	302 Found	src/Concerns/DeterminesStatusCode.php52-55
notModified()	304 Not Modified	src/Concerns/DeterminesStatusCode.php60-63
badRequest()	400 Bad Request	src/Concerns/DeterminesStatusCode.php68-71
unauthorized()	401 Unauthorized	src/Concerns/DeterminesStatusCode.php76-79
paymentRequired()	402 Payment Required	src/Concerns/DeterminesStatusCode.php84-87
forbidden()	403 Forbidden	src/Concerns/DeterminesStatusCode.php92-95
notFound()	404 Not Found	src/Concerns/DeterminesStatusCode.php100-103
requestTimeout()	408 Request Timeout	src/Concerns/DeterminesStatusCode.php108-111
conflict()	409 Conflict	src/Concerns/DeterminesStatusCode.php116-119
unprocessableContent()	422 Unprocessable Content	src/Concerns/DeterminesStatusCode.php124-127
unprocessableEntity()	422 (alias for unprocessableContent())	src/Concerns/DeterminesStatusCode.php132-135
tooManyRequests()	429 Too Many Requests	src/Concerns/DeterminesStatusCode.php140-143

Sources: src/Concerns/DeterminesStatusCode.php1-144

---

Error Handling and Exceptions

The Response class provides multiple methods for handling errors and throwing exceptions based on response status.

Exception Throwing Flow

Sources: src/Response.php236-373

Exception Methods

Method	Description	Line Reference
toException()	Creates a RequestException if the response failed; returns null otherwise	src/Response.php283-290
throw(?callable $callback)	Throws a RequestException if the response failed; optionally executes callback before throwing	src/Response.php297-310
throwIf(bool|Closure $condition, ?callable $callback)	Throws exception if condition is true and response failed	src/Response.php317-320
throwIfStatus(callable|int $statusCode)	Throws exception if status code matches; accepts callable for custom logic	src/Response.php329-337
throwUnlessStatus(callable|int $statusCode)	Throws exception unless status code matches	src/Response.php346-353
throwIfClientError()	Throws exception if status is 400-499	src/Response.php360-363
throwIfServerError()	Throws exception if status is 500+	src/Response.php370-373
onError(callable $callback)	Executes callback if response failed; returns $this for chaining	src/Response.php237-244

Sources: src/Response.php236-373

---

Debugging Methods

The Response class provides debugging utilities for inspecting response data during development.

Debug Method Flow

Sources: src/Response.php380-431

Method	Description	Returns	Line Reference
dump(?string $key)	Dumps the response body (auto-detects JSON); supports dot notation key	static	src/Response.php380-397
dd(?string $key)	Dumps the response body and exits the script	never	src/Response.php404-409
dumpHeaders()	Dumps the response headers	static	src/Response.php414-419
ddHeaders()	Dumps the response headers and exits the script	never	src/Response.php426-431

The dump() method automatically attempts to decode JSON. If successful, it dumps the decoded data; otherwise, it dumps the raw body string. When a key is provided, it uses dot notation to access nested data.

Sources: src/Response.php380-431

---

Resource Management

The Response class provides a method for closing the underlying stream and resources.

Method	Description	Line Reference
close()	Closes the response body stream and any underlying resources	src/Response.php265-270

Sources: src/Response.php265-270

---

PSR-7 Interoperability

The Response class wraps a PSR-7 ResponseInterface and provides a method to access the underlying PSR-7 response.

Method	Return Type	Description	Line Reference
toPsrResponse()	ResponseInterface	Returns the underlying PSR-7 response object	src/Response.php275-278

The Response class also implements dynamic method forwarding to the underlying PSR-7 response through the __call() magic method src/Response.php495-500 allowing direct access to any PSR-7 response methods not explicitly defined in the Response class.

Sources: src/Response.php54 src/Response.php275-278 src/Response.php495-500

---

Extensibility with Macros

The Response class uses the Macroable trait from Hyperf, allowing runtime extension with custom methods.

The __call() method first checks for macros before forwarding to the underlying PSR-7 response src/Response.php495-500

Sources: src/Response.php27-29 src/Response.php495-500

---

Response Property Summary

The Response class exposes two public properties for advanced use cases:

Property	Type	Purpose	Line Reference
$cookies	?CookieJar	Contains cookies from the response	src/Response.php44
$transferStats	?TransferStats	Contains transfer statistics including effective URI and handler stats	src/Response.php49

These properties are set by the PendingRequest class during request execution and are accessed by various response methods.

Sources: src/Response.php42-49