Download the PHP package larsmbergvall/json-api-resources-for-laravel without Composer

JSON:API Resources for Laravel

Table of Contents

• Example
• Installation
• Usage
• Attributes
  • JsonApiType
  • JsonApiIncludeAttributes
  • JsonApiIncludeRelationships
• Creating JsonApiResources
• Middleware
• The JsonApiResource class
• The JsonApiResourceCollection class
• Error transformation
• Testing
• Changelog
• Credits
• License

Example

This is an example of the output generated by this package:

Returns this:

Installation

You can install the package via composer:

It is recommended to use the middleware, either on all API calls:

Or, on a per-route basis:

Usage

Attributes

This package uses PHP 8 attributes to annotate Eloquent models. There is no need for additional resource classes. Attributes are used like this:

#[JsonApiType(string)]

This attribute can be used to change the value of the type property in the final output json. This attribute is optional. If it is not used, type will be set to the singular version of the models name, i.e. 'type' => 'book'.

#[JsonApiIncludeAttributes(string[])]

This attribute can be used to specify which of the models attributes should be included in the final output json. This attribute is optional. If it is not used, all visible model attributes will be included. It uses $model->attributesToArray() to get the attributes, so it will respect any $hidden fields.

#[JsonApiIncludeRelationships(string[])]

This attribute can be used to specify which of the models relationships should be included. This attribute is optional. If it is not used, no relationships will be included in the final output json.

NOTE: Regardless of what is included by this attribute, JsonApiResource only includes eager loaded relationships.

Creating JsonApiResources

If you have a single model, you should use JsonApiResource:

If you have a collection of models, you should use JsonApiResourceCollection:

If you need to manually return a JSON:API response, or don't want to use the middleware, you can use the jsonApiResponse()-helper:

It sets the correct Content-Type header for JSON:API responses. Note that it doesn't transform validation errors.

Middleware

The middleware primarily takes care of two things:

1. Making sure the response that is returned has the correct headers etc.
2. Transforming Laravels validation errors into the expected JSON:API error format

The middleware should be executed after any other middlewares that could change the Content-Type header of the response.

The JsonApiResource class

This class has a few public methods that you can use. Most likely you will not need to, because the JsonApiResourceCollection class handles that stuff automatically.

However, there is an important method: withIncluded(). By default, a JsonApiResource does not include it's related data. If you however run $resource->withIncluded() (or JsonApiResource::make($book)->withIncluded()) it will do so.

NOTE: It only includes eager loaded relationships, so if you need to exclude something for a certain api route you can just choose not to load a relationship. However, it includes related data recursively, meaning that it also includes data related to the included data.

The JsonApiResourceCollection class

This class also has the withIncluded() method that you can use to include any related data to your resources. Just as with the JsonApiResource, it only includes relations that are already loaded. However, it includes related data recursively, meaning that it also includes data related to the included data.

Error transformation

When validation fails in Laravel, normally you get a response that looks like this:

But with the JsonApiMiddleware, this response changes to:

Testing

There are some testing utilities on the JsonApiResource and JsonApiResourceCollection classes that you can utilize to test your application.

Note that more testing utilities will be coming in future versions!

assertHasData

assertDoesntHaveData

This is the opposite of assertHasData. It will fail if it finds the expected data.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Lars Bergvall
• All Contributors
• Spatie for the amazing Laravel package skeleton

License

The MIT License (MIT). Please see License File for more information.