Download the PHP package yzen.dev/laravel-json-api-response without Composer

JsonApiResponse

JsonApiResponse helps you build JSON:API-compatible response payloads with small responder classes.

The package is framework-light: the responder logic itself works with plain PHP objects and arrays, while HTTP responses and paginated lists use Laravel components:

• illuminate/http
• illuminate/pagination

Installation

Requirements

• PHP ^8.0
• illuminate/http
• illuminate/pagination

Basic Responder

Create a responder by extending AbstractResponder and implementing two methods:

Then compose a resource document:

The resulting payload follows the standard JSON:API shape:

By default, resourceId() returns $entity->id. Override it if your entity uses a different identifier.

Relationships

Define relationships in relationships() and pass the related records through withRelationData().

The relation data must be passed as a map keyed by the foreign key value:

If the foreign key is null, or the related object is missing from the map, the relationship value becomes null.

To-Many Relationships

Use ToManyRelationshipDefinition for grouped child resources:

Pass grouped data keyed by the parent entity field declared in entityKey:

Nested Relationship Data

If a child responder has its own relationships, pass that data through withNestedRelationData():

This is useful when a to-many relation needs nested linked resources without loading them inside the responder itself.

Includes

Top-level included resources are defined through includes():

Pass included entities as a flat array:

Paginated Lists

Use composeList() with Laravel's LengthAwarePaginator:

The package adds pagination metadata automatically:

HTTP Response Wrapper

YzendDev\Laravel\JsonApiResponse\Responder\JsonResponse extends Laravel's JsonResponse and sets JSON:API headers:

In a controller, a typical response looks like this:

Headers set by default:

• Content-type: application/vnd.api+json
• Charset: utf-8

Error Responses

Validation Errors

Ready-to-use JSON:API Error Documents

The package also ships a few ready-made JSON response classes:

• AuthenticationJsonApiException
• AuthorizationJsonApiException
• ResourceConflictJsonApiException
• ResourceNotFoundJsonApiException
• ErpSystemJsonApiException

Global Exception Handling

In Laravel, the package works best when JSON:API error rendering is configured once in bootstrap/app.php.

With this approach, application code can throw domain-level exceptions and let Laravel convert them into JSON:API error documents in one place:

That keeps controllers and services focused on business logic while response formatting stays centralized.

Notes

• Responders are intentionally passive. They format already loaded data and do not fetch dependencies themselves.
• Relationship maps and grouped child arrays should be prepared before calling the responder.
• The public usage model in this package follows the examples from responder.md.