JSON Resources

Purpose and Scope

This document explains the JSON resource system in the hypervel/http package, which provides API response formatting through the JsonResource, ResourceCollection, and AnonymousResourceCollection classes. These classes transform application data (models, collections, arrays) into consistently formatted JSON responses.

The resource system acts as a transformation layer between your application's data structures and the JSON sent to API clients. It handles single resources, collections, and paginated results while supporting selective attribute exposure and custom metadata injection.

For basic JSON response creation, see Response Types. For details on the Response object, see Response Object & Contract.

Sources: src/Resources/Json/JsonResource.php1-23 src/Resources/Json/ResourceCollection.php1-14 src/Resources/Json/AnonymousResourceCollection.php1-27

Architecture Overview

The resource system extends Hyperf\Resource\Json\JsonResource and Hyperf\Resource\Json\ResourceCollection base classes. Hypervel's implementation adds the UrlRoutable interface for routing integration and the CollectsResources trait for enhanced collection processing.

Core Components

Component	Location	Base Class	Purpose
JsonResource	src/Resources/Json/JsonResource.php	Hyperf\Resource\Json\JsonResource	Single resource transformation
ResourceCollection	src/Resources/Json/ResourceCollection.php	Hyperf\Resource\Json\ResourceCollection	Named collection transformation
AnonymousResourceCollection	src/Resources/Json/AnonymousResourceCollection.php	ResourceCollection	Dynamic collection creation
CollectsResources	src/Resources/Concerns/CollectsResources.php	Trait	Collection mapping logic

Sources: src/Resources/Json/JsonResource.php1-23 src/Resources/Json/ResourceCollection.php1-14 src/Resources/Json/AnonymousResourceCollection.php1-27 src/Resources/Concerns/CollectsResources.php1-35

Class Hierarchy

Diagram: Resource Class Inheritance Structure

Sources: src/Resources/Json/JsonResource.php7-12 src/Resources/Json/ResourceCollection.php7-10 src/Resources/Json/AnonymousResourceCollection.php13

JsonResource

The JsonResource class is the base class for transforming single data objects into JSON. It extends Hyperf\Resource\Json\JsonResource and implements Hypervel\Router\Contracts\UrlRoutable.

Key Characteristics:

Aspect	Details
Namespace	Hypervel\Http\Resources\Json
Extends	Hyperf\Resource\Json\JsonResource
Implements	Hypervel\Router\Contracts\UrlRoutable
Location	src/Resources/Json/JsonResource.php12

Static Method: collection()

The collection() method transforms arrays or collections of items into an AnonymousResourceCollection:

src/Resources/Json/JsonResource.php14-22

Operation sequence:

1. Creates AnonymousResourceCollection with the resource data and current class name as the $collects parameter
2. Uses tap() helper to configure the collection instance
3. Transfers preserveKeys setting from a temporary resource instance to the collection
4. Returns the configured AnonymousResourceCollection

Example call pattern:

Sources: src/Resources/Json/JsonResource.php14-22

ResourceCollection

The ResourceCollection class handles named collection transformations. It extends Hyperf\Resource\Json\ResourceCollection and uses the CollectsResources trait for collection mapping logic.

Class definition:

src/Resources/Json/ResourceCollection.php1-14

The CollectsResources trait src/Resources/Json/ResourceCollection.php12 provides the collectResource() method, which handles:

• Array to Collection conversion
• Item mapping via mapInto() when items aren't already resource instances
• Paginator resource detection and handling

This class is used when you need a dedicated collection class with custom behavior, rather than using the anonymous collection created by JsonResource::collection().

Sources: src/Resources/Json/ResourceCollection.php1-14

AnonymousResourceCollection

The AnonymousResourceCollection class represents dynamically created collections via JsonResource::collection(). It extends ResourceCollection and binds the resource type at instantiation.

Class structure:

src/Resources/Json/AnonymousResourceCollection.php1-27

Constructor Parameters

Parameter	Type	Purpose
$resource	mixed	The collection being wrapped (array, Collection, paginator)
$collects	string	Fully qualified class name of the resource type (e.g., UserResource::class)

The constructor src/Resources/Json/AnonymousResourceCollection.php21-26 sets the $collects property before calling the parent constructor, ensuring the collection knows which resource class to instantiate for each item.

Created by: src/Resources/Json/JsonResource.php19 when calling JsonResource::collection($items)

Sources: src/Resources/Json/AnonymousResourceCollection.php1-27 src/Resources/Json/JsonResource.php17-22

CollectsResources Trait

The CollectsResources trait provides collection mapping logic for ResourceCollection. It implements the collectResource() method that transforms various input types into resource collections.

Diagram: collectResource() Processing Logic

Method Implementation

The collectResource() method src/Resources/Concerns/CollectsResources.php15-34 performs these operations:

1. Early Return for MissingValue src/Resources/Concerns/CollectsResources.php17-19

• If $resource instanceof MissingValue, return immediately without processing

2. Array to Collection Conversion src/Resources/Concerns/CollectsResources.php21-23

• Convert array input to Hypervel\Support\Collection instance

3. Resource Mapping src/Resources/Concerns/CollectsResources.php25-29

• Get target class name from $this->collects()
• Check if first item is already an instance of target class
• If not already instantiated: use $resource->mapInto($collects) to wrap each item
• If already instantiated: use $resource->toBase() to normalize collection
• Store result in $this->collection property

4. Paginator Preservation src/Resources/Concerns/CollectsResources.php31-33

• Detect paginator resources using $this->isPaginatorResource($resource)
• For paginators: call $resource->setCollection($this->collection) to preserve pagination metadata
• For non-paginators: return the transformed collection directly

Sources: src/Resources/Concerns/CollectsResources.php1-35

Data Flow Architecture

Diagram: Resource Transformation Pipeline

Sources: src/Resources/Json/JsonResource.php17-22 src/Resources/Json/ResourceCollection.php12 src/Resources/Concerns/CollectsResources.php15-34 src/Response.php220-228

Usage Patterns

Single Resource Transformation

For transforming a single model or data object, extend JsonResource and define a toArray() method in your custom resource class. The base implementation handles the response creation.

Collection Transformation

There are two approaches for collection transformation:

1. Anonymous Collections: Created via JsonResource::collection() src/Resources/Json/JsonResource.php17-22

   • Quick method for transforming collections
   • Uses the resource's preserveKeys setting
   • Returns AnonymousResourceCollection instance

2. Named Collections: Extend ResourceCollection src/Resources/Json/ResourceCollection.php10-13

   • For collections requiring custom behavior
   • Automatically uses CollectsResources trait
   • Supports complex collection mapping logic

Paginator Support

The CollectsResources trait includes special handling for paginated resources src/Resources/Concerns/CollectsResources.php31-33:

• Detects paginator resources via isPaginatorResource()
• Transforms items within the paginator
• Preserves pagination metadata
• Returns paginator with transformed collection

Integration with Response System

Resource classes integrate with the response system through Hyperf's resource infrastructure. When a resource is returned from a controller, it is automatically serialized to JSON and wrapped in an appropriate HTTP response.

The UrlRoutable interface on JsonResource src/Resources/Json/JsonResource.php12 enables resources to be used in routing contexts, allowing framework features that expect routable objects to work with resources.

Sources: src/Resources/Json/JsonResource.php12 src/Resources/Json/ResourceCollection.php1-14 src/Resources/Concerns/CollectsResources.php1-35