Collections

The Collection class provides an enhanced collection implementation that extends Hyperf's base collection with automatic resource transformation capabilities for API responses. This page documents the collection's resource transformation features and resolution strategies.

For general data manipulation utilities, see Data Manipulation. For helper functions that create collections, see Helper Functions.

Overview

The Collection class extends Hyperf\Collection\Collection and adds the ability to automatically transform collections into API resource collections through the TransformsToResourceCollection trait.

Sources: src/Collection.php1-19

Class Definition

The Collection class is a generic type that preserves type information for keys and values:

Component	Description
Namespace	Hypervel\Support
Extends	Hyperf\Collection\Collection
Traits	TransformsToResourceCollection
Generics	@template TKey of array-key, @template TValue

Sources: src/Collection.php10-19

Base Collection Features

The Collection class inherits all fluent methods from Hyperf's base collection implementation, including:

• Transformation: map(), filter(), reduce(), transform()
• Aggregation: sum(), avg(), min(), max(), count()
• Partitioning: chunk(), split(), partition()
• Ordering: sort(), sortBy(), sortByDesc()
• Retrieval: first(), last(), get(), pluck()

These methods are documented in Hyperf's collection documentation and are not extended by the hypervel/support package.

Sources: src/Collection.php7-19

Resource Transformation

The primary enhancement provided by Hypervel\Support\Collection is the toResourceCollection() method, which transforms a collection of models into an API resource collection suitable for HTTP responses.

Sources: src/Traits/TransformsToResourceCollection.php19-32

Method Signature

Parameter	Type	Description
$resourceClass	?string	Optional fully-qualified resource class name
Returns	ResourceCollection	The transformed resource collection
Throws	Throwable	If resource resolution fails

Sources: src/Traits/TransformsToResourceCollection.php20-32

Resource Resolution Strategy

When toResourceCollection() is called without an explicit resource class, the trait employs a multi-stage resolution strategy to determine the appropriate resource.

Sources: src/Traits/TransformsToResourceCollection.php34-86

Resolution Stages

The guessResourceCollection() method implements the following resolution stages in order:

Stage 1: Empty Collection Check

Returns a default ResourceCollection if the collection is empty, avoiding resolution errors.

Sources: src/Traits/TransformsToResourceCollection.php41-43

Stage 2: Object Validation

Validates that the first collection item is an object. Throws LogicException if not.

Sources: src/Traits/TransformsToResourceCollection.php45-47

Stage 3: Method Validation

Ensures the model class implements the guessResourceName() method, typically provided by the TransformsToResource trait.

Sources: src/Traits/TransformsToResourceCollection.php52-56

Stage 4: Attribute-Based Resolution

The trait checks for PHP 8 attributes on the model class:

Attribute	Priority	Description
UseResourceCollection	1st	Directly specifies the resource collection class
UseResource	2nd	Specifies the resource class (collection auto-generated)

Sources: src/Traits/TransformsToResourceCollection.php58-68 src/Traits/TransformsToResourceCollection.php88-124

Stage 5: Name-Based Resolution

If attributes are not found, the trait calls $model::guessResourceName() to get candidate resource class names and attempts resolution in two passes:

Pass 1: Dedicated Collection Classes

Looks for dedicated resource collection classes (e.g., UserResourceCollection for UserResource).

Sources: src/Traits/TransformsToResourceCollection.php72-77

Pass 2: Resource::collection() Static Method

Falls back to using the resource's static collection() method to create a generic resource collection.

Sources: src/Traits/TransformsToResourceCollection.php79-83

Stage 6: Failure

If all resolution stages fail, a LogicException is thrown:

Sources: src/Traits/TransformsToResourceCollection.php85

Attribute-Based Configuration

Models can use PHP 8 attributes to explicitly declare their resource classes, bypassing the guessing mechanism.

UseResourceCollection Attribute

Directly specifies the resource collection class:

The trait resolves this attribute via reflection:

Sources: src/Traits/TransformsToResourceCollection.php107-124

UseResource Attribute

Specifies the individual resource class (collection auto-generated via ::collection() method):

Sources: src/Traits/TransformsToResourceCollection.php88-105

Attribute Resolution Implementation

Method	Return Type	Purpose
resolveResourceCollectionFromAttribute()	?string	Extracts class from UseResourceCollection attribute
resolveResourceFromAttribute()	?string	Extracts class from UseResource attribute

Both methods use PHP reflection to inspect class attributes:

1. Create ReflectionClass instance for the model
2. Call getAttributes() with the attribute class
3. Instantiate the attribute and return its class property
4. Return null if attribute not found

Sources: src/Traits/TransformsToResourceCollection.php88-124

Integration with HTTP Resources

The toResourceCollection() method produces instances of Hypervel\Http\Resources\Json\ResourceCollection, which are designed for HTTP API responses.

Sources: src/Traits/TransformsToResourceCollection.php9

Typical Usage Pattern

The resulting ResourceCollection is automatically serialized to JSON when returned from a controller method.

Error Handling

The trait throws LogicException in the following scenarios:

Condition	Error Message
Non-object items	"Resource collection guesser expects the collection to contain objects."
Missing guessResourceName()	"Expected class %s to implement guessResourceName method. Make sure the model uses the TransformsToResource trait."
No resource found	"Failed to find resource class for model [%s]."

All error checking uses the throw_unless() helper for conditional exception throwing.

Sources: src/Traits/TransformsToResourceCollection.php47 src/Traits/TransformsToResourceCollection.php52-56 src/Traits/TransformsToResourceCollection.php85

Relationship to Global Helpers

The collect() helper function (documented in Helper Functions) creates instances of this Collection class:

This means all collections created via the collect() helper automatically have access to the toResourceCollection() method.

Sources: Referenced from high-level architecture diagrams