Response Transformation

Purpose and Scope

This document explains how API responses are transformed into different output formats. The ApiResource class implements multiple PHP interfaces that enable automatic conversion to arrays, JSON, and strings. This transformation system allows responses to be seamlessly integrated with PHP's native serialization mechanisms and framework features.

For information about accessing individual fields from response data, see Accessing Response Data. For details on response metadata (status codes, headers), refer to the ApiResponse class documentation in the Core Architecture section.

Key Topics Covered:

• Array transformation via Arrayable interface
• JSON transformation via Jsonable and JsonSerializable interfaces
• String transformation via Stringable interface
• The relationship between ApiResource and ApiResponse data methods
• Practical serialization patterns

---

Overview

The ApiResource class implements five PHP interfaces that enable automatic data transformation:

Interface	Purpose	Primary Method
Stringable	Convert to string representation	__toString()
ArrayAccess	Enable array-style access to data	offsetGet(), offsetSet(), etc.
JsonSerializable	Enable json_encode() compatibility	jsonSerialize()
Arrayable	Convert to PHP array (Hyperf convention)	toArray()
Jsonable	Convert to JSON string (Hyperf convention)	toJson()

These interfaces allow ApiResource instances to be used in contexts expecting arrays, JSON, or strings without explicit conversion.

Sources: src/ApiResource.php18 src/ApiResource.php1-147

---

Transformation Architecture

Transformation Flow:

1. Application Context invokes transformation based on usage context
2. ApiResource implements interface methods that delegate to ApiResponse
3. ApiResponse provides body() for raw strings and json() for parsed arrays
4. Raw Data is returned in the appropriate format

Sources: src/ApiResource.php18 src/ApiResource.php31-34 src/ApiResource.php95-114 src/ApiResource.php25-29

---

String Transformation

Stringable Interface

The ApiResource class implements PHP's Stringable interface, allowing automatic conversion to string when used in string contexts:

All these operations invoke the __toString() magic method.

Sources: src/ApiResource.php18 src/ApiResource.php31-34

Implementation

The __toString() method delegates to the underlying ApiResponse::body() method, returning the raw HTTP response body as a string:

Key Characteristics:

• Returns the raw, unprocessed HTTP response body
• No JSON parsing or data transformation is applied
• Useful for debugging, logging, or working with non-JSON responses
• Cannot throw exceptions (PHP limitation of __toString())

Sources: src/ApiResource.php31-34 src/ApiResource.php25-29

String Transformation Flow

Sources: src/ApiResource.php31-34 src/ApiResource.php25-29

---

Array Transformation

Arrayable Interface

The Arrayable interface (from hyperf/contract) provides a consistent method for converting objects to arrays. The ApiResource class implements this interface through the toArray() method:

Sources: src/ApiResource.php9 src/ApiResource.php18 src/ApiResource.php103-106

Implementation

The toArray() method delegates to ApiResponse::json(), which parses the JSON response body:

Key Characteristics:

• Assumes the response body is valid JSON
• Returns parsed array structure
• Enables framework integration (e.g., Hyperf serialization)
• Used internally by resolve() and jsonSerialize()

Sources: src/ApiResource.php103-106 src/ApiResource.php25-29

Resolve Method

The resolve() method provides an alias for toArray() and is used internally by JSON serialization:

This method exists to provide semantic clarity when resolving resources for serialization contexts.

Sources: src/ApiResource.php95-98

Array Transformation Flow

Sources: src/ApiResource.php103-106 src/ApiResource.php25-29

---

JSON Transformation

JsonSerializable Interface

The JsonSerializable interface enables ApiResource to work seamlessly with PHP's json_encode() function:

When json_encode() encounters an object implementing JsonSerializable, it calls the jsonSerialize() method.

Sources: src/ApiResource.php12 src/ApiResource.php18 src/ApiResource.php111-114

Implementation

The jsonSerialize() method delegates to resolve(), which in turn calls toArray():

Method Chain:

1. json_encode($resource) invokes jsonSerialize()
2. jsonSerialize() calls resolve()
3. resolve() calls toArray()
4. toArray() calls $this->response->json()
5. Returns parsed array structure for encoding

Sources: src/ApiResource.php111-114 src/ApiResource.php95-98 src/ApiResource.php103-106

Jsonable Interface

The Jsonable interface (from hyperf/contract) provides an explicit toJson() method:

While not explicitly defined in ApiResource, this method is typically available through the ApiResponse class and can be forwarded via the __call() magic method.

Sources: src/ApiResource.php10 src/ApiResource.php18 src/ApiResource.php63-72

JSON Transformation Flow

Sources: src/ApiResource.php111-114 src/ApiResource.php95-98 src/ApiResource.php103-106

---

Interface Implementation Summary

The ApiResource class implements five distinct interfaces to enable comprehensive data transformation:

Interface	Method	Return Type	Delegation Target
Stringable	__toString()	string	ApiResponse::body()
Arrayable	toArray()	array	ApiResponse::json()
Jsonable	toJson()	string	Forwarded via __call()
JsonSerializable	jsonSerialize()	mixed	resolve() → toArray()
ArrayAccess	offsetGet(), offsetSet(), etc.	mixed	ApiResponse methods

Sources: src/ApiResource.php18 src/ApiResource.php31-34 src/ApiResource.php103-106 src/ApiResource.php111-114 src/ApiResource.php119-146

Transformation Method Relationships

Key Observations:

• All transformations ultimately rely on ApiResponse::body() or ApiResponse::json()
• jsonSerialize() chains through resolve() to toArray()
• String and array transformations are independent paths
• JSON encoding uses the array transformation path

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

---

ArrayAccess Implementation

The ApiResource class implements ArrayAccess to enable array-style access to response data. All array access operations are delegated to the underlying ApiResponse:

Sources: src/ApiResource.php18 src/ApiResource.php119-146

ArrayAccess Method Delegation

All ArrayAccess methods delegate to ApiResponse:

Sources: src/ApiResource.php119-146

Property Access

The ApiResource class also supports property-style access via magic methods:

These magic methods also delegate to the ApiResponse:

Sources: src/ApiResource.php39-58

---

Practical Examples

Example 1: String Serialization

Sources: src/ApiResource.php31-34

Example 2: Array Serialization

Sources: src/ApiResource.php103-106

Example 3: JSON Serialization

Sources: src/ApiResource.php111-114

Example 4: Mixed Access Patterns

Sources: src/ApiResource.php31-34 src/ApiResource.php55-58 src/ApiResource.php103-106 src/ApiResource.php111-114 src/ApiResource.php127-130

Example 5: Framework Integration

Sources: src/ApiResource.php18 src/ApiResource.php31-34 src/ApiResource.php103-106 src/ApiResource.php111-114

---

Summary

Response metadata access in the hypervel/api-client package follows a layered architecture:

1. PSR-7 Foundation: All responses are PSR-7 compliant at the lowest level
2. HttpClientResponse Layer: Provides convenient methods for accessing status, headers, body
3. ApiResponse Layer: Adds immutable PSR-7 modification methods and context storage
4. ApiResource Layer: Forwards all metadata methods transparently via __call()

Key Concepts:

• Status codes and convenience methods (successful(), failed(), etc.) are available on ApiResource
• Headers can be accessed and checked via header(), headers(), hasHeader()
• Immutable modifications require accessing ApiResponse via getResponse()
• Context storage provides custom metadata beyond HTTP standards
• All methods maintain PSR-7 compliance and immutability patterns

Sources: src/ApiResponse.php1-67 src/ApiResource.php1-147