ApiResource

Purpose and Scope

The ApiResource class serves as the final transformation layer in the response handling pipeline, providing a unified interface for accessing API response data through multiple patterns (array access, property access, method calls, and JSON serialization). This document covers the structure, capabilities, and usage of ApiResource as the primary return type for API requests.

For information about how ApiResource is created and returned, see PendingRequest. For details about the underlying response wrapper, see ApiResponse. For consuming response data in application code, see Accessing Response Data.

---

Overview

ApiResource is a wrapper class that encapsulates both ApiResponse and ApiRequest objects, providing a rich interface for consuming API response data. It implements multiple standard PHP interfaces to enable flexible data access patterns and acts as a facade that delegates most operations to the underlying ApiResponse instance.

Location: src/ApiResource.php1-148

Key Characteristics:

• Encapsulates ApiResponse and ApiRequest instances
• Implements ArrayAccess, JsonSerializable, Arrayable, Jsonable, and Stringable interfaces
• Uses ForwardsCalls trait for method delegation
• Annotated with @mixin ApiResponse for IDE support
• Provides property-style access to response data
• Acts as the final return type for all API requests

Sources: src/ApiResource.php1-30

---

Class Structure

Implemented Interfaces and Traits

Interface Implementations:

Interface	Purpose	Methods Implemented
Stringable	Enables string conversion	__toString()
ArrayAccess	Enables array-style access	offsetExists(), offsetGet(), offsetSet(), offsetUnset()
JsonSerializable	Enables JSON encoding	jsonSerialize()
Arrayable	Provides array conversion	toArray()
Jsonable	Provides JSON string conversion	Inherited from interface

Sources: src/ApiResource.php7-21 src/ApiResource.php18

---

Construction and Lifecycle

Constructor

The ApiResource constructor requires both an ApiResponse and an ApiRequest instance:

Location: src/ApiResource.php25-29

These protected properties store references to both the response and the original request that generated it, enabling full access to both the response data and request context.

Creation Flow

Typical Creation Pattern (from PendingRequest):

1. PendingRequest executes HTTP request via ApiRequest
2. Raw PSR-7 response is wrapped in ApiResponse
3. Response middleware is applied (if enabled)
4. ApiResource is instantiated with both response and request
5. Resource is returned to application code

Sources: src/ApiResource.php25-29

Static Factory Method

The make() method provides an alternative construction pattern:

Location: src/ApiResource.php87-90

This enables subclasses to override construction logic while maintaining a consistent creation interface.

Sources: src/ApiResource.php87-90

---

Data Access Patterns

ApiResource provides multiple ways to access response data, all of which delegate to the underlying ApiResponse instance.

Property Access via Magic Methods

Implementation:

Method	Purpose	Delegation Target
__get($key)	Access property	$this->response->offsetGet($key)
__isset($key)	Check property existence	isset($this->response->json()[$key])
__unset($key)	Remove property	$this->response->offsetUnset($key)

Locations:

• src/ApiResource.php39-50 - __isset() implementation
• src/ApiResource.php55-58 - __get() implementation

Example Usage:

Sources: src/ApiResource.php39-58

Array Access via ArrayAccess Interface

All ArrayAccess methods directly delegate to the corresponding ApiResponse methods:

Locations: src/ApiResource.php118-146

Example Usage:

Sources: src/ApiResource.php118-146

Method Call Forwarding

The __call() magic method forwards any method calls to the underlying ApiResponse instance using the ForwardsCalls trait:

Location: src/ApiResource.php63-72

This enables calling any ApiResponse method directly on the ApiResource instance. The @mixin ApiResponse annotation at the class level provides IDE autocomplete support for forwarded methods.

Example Usage:

Sources: src/ApiResource.php16 src/ApiResource.php63-72

Delegation Pattern Overview

Sources: src/ApiResource.php31-72 src/ApiResource.php118-146

---

Serialization and Conversion

String Conversion

The __toString() method enables direct string conversion by returning the raw response body:

Location: src/ApiResource.php31-34

Example Usage:

Sources: src/ApiResource.php31-34

Array Conversion

The toArray() method converts the resource to an array by delegating to ApiResponse::json():

Location: src/ApiResource.php103-106

The resolve() method is an alias for toArray():

Location: src/ApiResource.php95-98

Sources: src/ApiResource.php95-106

JSON Serialization

The jsonSerialize() method enables JSON encoding via json_encode():

Location: src/ApiResource.php111-114

Example Usage:

Conversion Flow

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

---

Accessing Encapsulated Objects

ApiResource provides getter methods to access the encapsulated request and response objects directly:

Getting the Response

Location: src/ApiResource.php74-77

Usage: Access the underlying ApiResponse instance to call methods that aren't forwarded or to access response metadata directly.

Getting the Request

Location: src/ApiResource.php79-82

Usage: Access the original ApiRequest instance to inspect request details, headers, URL, method, or context data.

Example:

Sources: src/ApiResource.php74-82

---

Extension and Customization

Subclassing ApiResource

The ApiResource class can be extended to create domain-specific resource types with custom behavior:

Custom Resource Pattern:

1. Extend ApiResource
2. Add domain-specific methods
3. Override make() if custom construction needed
4. Configure ApiClient with generic type parameter

Benefits:

• Type-safe access to specific API endpoints
• Custom business logic in resource objects
• IDE autocomplete for domain methods
• Centralized response transformation logic

Sources: src/ApiResource.php87-90

---

Complete Data Flow

This diagram shows the complete flow of data through ApiResource from creation to consumption:

Sources: src/ApiResource.php1-148

---

Summary

ApiResource serves as the final transformation layer in the API client architecture, providing:

Core Responsibilities:

• Encapsulates both ApiResponse and ApiRequest instances
• Provides unified interface for accessing response data
• Delegates operations to underlying ApiResponse
• Implements multiple PHP interfaces for flexible data access
• Supports custom subclassing for domain-specific resources

Access Patterns:

• Property access via __get(), __isset(), __unset()
• Array access via ArrayAccess interface
• Method forwarding via __call() and ForwardsCalls trait
• String conversion via __toString()
• Array conversion via toArray() and resolve()
• JSON serialization via jsonSerialize()

Integration Points:

• Created by PendingRequest after response middleware
• Wraps ApiResponse for response data access
• Wraps ApiRequest for request context access
• Returns to application code as final API call result

Sources: src/ApiResource.php1-148