Accessing Response Data

Purpose and Scope

This page documents how to access data from API responses using the ApiResource class. When a request is executed, it returns an ApiResource instance that wraps the ApiResponse and provides multiple convenient interfaces for accessing response data.

For information about transforming responses and accessing metadata (status codes, headers, etc.), see Response Transformation. For information about type-safe resource classes, see Type Safety.

---

Overview

The ApiResource class serves as a type-safe wrapper around ApiResponse that provides multiple access patterns for response data. It implements several PHP interfaces to enable flexible data access:

Interface	Purpose
ArrayAccess	Access response data using array syntax
Arrayable	Convert response to array via toArray()
Jsonable	Convert response to JSON string
JsonSerializable	Support json_encode() serialization
Stringable	Cast response to string

The class automatically decodes JSON responses and makes the data accessible through property access, array access, and various transformation methods.

Sources: src/ApiResource.php18

---

Access Patterns

Property Access

The most straightforward way to access response data is through property syntax using the magic __get() method. This provides a clean, object-oriented interface to JSON fields.

Property Access Flow

When accessing a property on ApiResource, the following occurs:

1. The __get() method intercepts the property access src/ApiResource.php55-58
2. It delegates to ApiResponse::offsetGet() to retrieve the value from the decoded JSON data
3. The value is returned directly to the caller

Example Usage:

You can also check if a property exists using isset() or empty(), which are handled by the __isset() method src/ApiResource.php39-42:

Sources: src/ApiResource.php39-42 src/ApiResource.php55-58

---

Array Access

ApiResource implements the ArrayAccess interface, allowing you to access response data using array syntax. This is particularly useful when working with dynamic keys or when the field name conflicts with PHP reserved words.

ArrayAccess Methods

All four ArrayAccess methods are implemented and delegate to the underlying ApiResponse:

Method	Line Reference	Purpose
offsetExists()	src/ApiResource.php119-122	Check if a key exists
offsetGet()	src/ApiResource.php127-130	Retrieve a value by key
offsetSet()	src/ApiResource.php135-138	Set a value by key
offsetUnset()	src/ApiResource.php143-146	Remove a key

Example Usage:

Sources: src/ApiResource.php119-146

---

Array Conversion

The toArray() method converts the entire response to a PHP array, which is useful for bulk data operations or passing data to other systems.

Array Conversion Flow

The toArray() method src/ApiResource.php103-106 delegates to ApiResponse::json(), which returns the decoded JSON response as a PHP array.

Example Usage:

The resolve() method src/ApiResource.php95-98 is an alias for toArray() that exists for framework compatibility:

Sources: src/ApiResource.php95-106

---

JSON Serialization

ApiResource implements JsonSerializable and Jsonable interfaces, allowing seamless integration with JSON encoding operations.

JSON Serialization Implementation

The jsonSerialize() method src/ApiResource.php111-114 implements the JsonSerializable interface and delegates to resolve(), which returns the array representation of the response.

Example Usage:

Sources: src/ApiResource.php111-114

---

String Casting

When cast to a string, ApiResource returns the raw response body. This is implemented via the __toString() magic method src/ApiResource.php31-34

String Casting Flow

The __toString() method delegates to ApiResponse::body() to retrieve the raw response body as a string.

Example Usage:

Note: String casting returns the raw body without any processing. For structured data access, use property access or array methods instead.

Sources: src/ApiResource.php31-34

---

Method Delegation

ApiResource uses the __call() magic method to delegate method calls to the underlying ApiResponse object. This allows you to call any ApiResponse method directly on the resource.

Method Delegation Implementation

The __call() method src/ApiResource.php63-72 performs the following:

1. Checks if the method exists on ApiResponse using method_exists()
2. If not found, throws a BadMethodCallException with a descriptive error message
3. If found, forwards the call using the ForwardsCalls trait

This delegation pattern means that all public methods of ApiResponse are available on ApiResource.

Example Usage:

Available Delegated Methods:

The following ApiResponse methods are commonly accessed through delegation:

• Response status methods: status(), successful(), ok(), failed()
• Header access: header(), headers()
• Body access: body(), json()
• Protocol information: getProtocolVersion()

For a complete list of available methods, see Response Transformation.

Sources: src/ApiResource.php63-72 src/ApiResource.php74-82

---

Access Pattern Comparison

The following table summarizes when to use each access pattern:

Pattern	Syntax	Use Case	Returns
Property Access	$resource->field	Clean, simple field access	Mixed value
Array Access	$resource['field']	Dynamic keys, reserved words	Mixed value
Array Conversion	$resource->toArray()	Bulk operations, array functions	Full array
JSON Serialization	json_encode($resource)	API responses, data transfer	JSON string
String Casting	(string) $resource	Raw body, logging	Raw body string
Method Delegation	$resource->method()	Access response metadata	Varies by method

Choosing an Access Pattern:

Sources: src/ApiResource.php1-147

---

Implementation Details

Interface Implementations

ApiResource implements multiple interfaces to provide a rich feature set src/ApiResource.php18:

Trait Usage

The class uses the ForwardsCalls trait src/ApiResource.php20 from Hyperf to enable safe method delegation:

This trait provides the forwardCallTo() method used in __call() to delegate method calls to the underlying ApiResponse object while maintaining proper error handling.

Constructor

The constructor src/ApiResource.php25-29 accepts and stores both the response and request objects:

These are accessible via:

• getResponse() src/ApiResource.php74-77
• getRequest() src/ApiResource.php79-82

Static Factory

The static make() method src/ApiResource.php87-90 provides a convenient way to create resource instances:

This is used internally by PendingRequest to instantiate resources after request execution.

Sources: src/ApiResource.php18-90

---

Data Flow Summary

Data Flow Description:

1. HTTP response is received and body is decoded to a PHP array
2. ApiResponse stores the decoded data
3. ApiResource wraps the response and provides multiple access interfaces
4. User code accesses data through any of the supported patterns
5. All access methods ultimately retrieve data from the decoded JSON array

Sources: src/ApiResource.php1-147