collections.md

Heterogeneous Collections

You can define collections that are heterogeneous – containing multiple kinds of resources. For example, an activity collection might contain posts, comments, and likes resources.

Heterogeneous collections can be exposed in the API through endpoints. They are also used for defining polymorphic relationships.

Defining Collections

To define a heterogeneous collection, create a new class that implements the Tobyz\JsonApi\Resource\Collection interface:

use Tobyz\JsonApiServer\Resource\Collection;

class ActivityCollection implements Collection
{
    /**
     * Get the collection name.
     */
    public function name(): string
    {
        return 'activity';
    }

    /**
     * Get the resources contained within this collection.
     */
    public function resources(): array
    {
        return ['posts', 'comments', 'likes'];
    }

    /**
     * Get the name of the resource that represents the given model.
     */
    public function resource(object $model, Context $context): ?string
    {
        return match (true) {
            $model instanceof Post => 'posts',
            $model instanceof Comment => 'comments',
            $model instanceof Like => 'likes',
            default => null,
        };
    }

    /**
     * The collection's endpoints.
     */
    public function endpoints(): array
    {
        return [];
    }
}

The name you choose will be used as the path for any endpoints, and relationships may also reference your collection by this name.

The resources array should contain the names of the resource types that can exist within the collection. This will be used to restrict which resources can be created or attached to this collection, as well as what relationships can be included.

The resource method maps a model to the resource type that should represent it in this collection.

The endpoints method should return an array of endpoint objects to expose your collection in the API. Refer to the Resources page for more information.

Registering Collections

Register an instance of your collection class with the API server using the collection() method:

$api = new JsonApi();

$api->collection(new ActivityCollection());