How to include pivot relationship data within the JSON:API resource toRelationships method?

[SantosVilanculos]

When implementing the toRelationships method in a Laravel JSON:API resource, what is the standard way to include a many-to-many relationship that requires access to pivot table attributes or custom accessors?

I am looking for the syntax to ensure that when withPivot or a custom Pivot model is used, the data is correctly mapped into the relationship's data.

[nirav-gajera]

Include pivot data in your resource attributes, not in the relationship definition.

Model Setup

public function roles()
{
    return $this->belongsToMany(Role::class)->withPivot('assigned_at');
}

Resource Implementation

class RoleResource extends JsonApiResource
{
    public function toAttributes(): array
    {
        return [
            'name' => $this->resource->name,

            'assignedAt' => $this->when(
                isset($this->resource->pivot),
                $this->resource->pivot?->assigned_at
            ),
        ];
    }

    public function toRelationships(): array
    {
        return [];
    }
}

User Resource

class UserResource extends JsonApiResource
{
    public function toRelationships(): array
    {
        return [
            'roles' => ToMany::make($this->roles),
        ];
    }
}

The RoleResource automatically includes pivot data when accessed through the relationship.

The standard approach is to:

1. Configure pivot data in your model using withPivot()
2. Include pivot attributes in the resource's toAttributes() method
3. Use custom pivot models for encapsulating pivot logic
4. Avoid mixing pivot data with relationship definitions

[SantosVilanculos]

The rule of thumb is to include pivot data in your resource attributes, not in the relationship definition?

[macropay-solutions]

This is the Laravel solution to get also pivot data. If you don't want it in the response do not add it in your resource.