Download the PHP package soyhuce/laravel-json-resources without Composer

An opinionated JsonResource for Laravel

Don't ever run database queries in JsonResource serialization, without overhead in production !

Installation

You can install the package via composer:

You can publish the config file with:

Usage

This package provides a base class Soyhuce\JsonResources\JsonResource.

It gives a simplified interface for data serialization :

It is still possible tu use public function toArray($request): array method.

A base class \Soyhuce\JsonResources\ResourceCollection est aussi disponible.

Forbid to execute database queries

Using this base resource, you can forbid to execute database queries during serialization.

You just need to activate this option in json-resources.forbid-database-queries config.

This configuration is thought to be used in local environments but should be deactivated in production. It allows you to tests that all required relations are correctly loaded (in feature tests for exemple) while limiting overhead in production.

For exemple :

A DatabaseQueryDetected exception will be raised with every executed request :

AnonymousResource

It could be useful to have anonymous resources for some cases.

For exemple if user's role is nullable, you could have :

Via an AnonymousResource, you could do

If the user has a role, you will get :

If the user doest not have a role, you will get :

Returning anonymous resource from the controller

It is possible to return an anonymous resource from the controller. In cas the provided data is null, you won't get ' null' but an empty array [].

If the item is found

If the item is null

Note : Anonymous resource collections are not supported

AnonymousResource without format

It is possible to return an anonymous resource without callback. In this case, the resource will be returned as is.

Le json retourné aura alors la forme

Json encoding

All returned jsons are encoded by default with JSON_PRESERVE_ZERO_FRACTION option.

Feature tests

The JsonResource and ResourceCollection classes will add a X-Json-Resource header to the response when the application is in local or testing environment.

This header will contain the actual resource class used to generate the response and can be used in functional tests to verify which resource was used.

In order to test this, you cas use TestResponse::assertJsonResource(TheResource::class) method.

Unit tests

It can be useful to unit test the JsonResource. You can use soyhuce/laravel-testing for this.

In this cas, you will probably need to allow database queries to be run. You can do this calling

Testing

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Bastien Philippe
• All Contributors

License

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