https://github.com/czim/laravel-jsonapi
Basic setup framework for creating a Laravel JSON-API server
https://github.com/czim/laravel-jsonapi
encoding-responses json-api laravel validation
Last synced: 5 months ago
JSON representation
Basic setup framework for creating a Laravel JSON-API server
- Host: GitHub
- URL: https://github.com/czim/laravel-jsonapi
- Owner: czim
- License: mit
- Archived: true
- Created: 2015-12-14T13:07:45.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2020-03-10T09:30:35.000Z (over 6 years ago)
- Last Synced: 2025-12-21T00:43:11.766Z (6 months ago)
- Topics: encoding-responses, json-api, laravel, validation
- Language: PHP
- Size: 311 KB
- Stars: 16
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
[![Latest Version on Packagist][ico-version]][link-packagist]
[![Software License][ico-license]](LICENSE.md)
[](https://travis-ci.org/czim/laravel-jsonapi)
[](https://coveralls.io/github/czim/laravel-jsonapi?branch=master)
# JSON-API Base
Basic application elements for JSON-API projects.
Offers means for quickly scaffolding JSON-API compliance for Laravel applications.
This does *NOT* provide the means to set up the API or the means for user authorisation.
## Disclaimer
This is very much a work in progress at this time. Interface- and other breaking changes may happen.
The old, discontinued version of this project is in the `0.9.5` branch.
## Version Compatibility
Laravel | Package
:-------------|:--------
5.3 | 1.3
5.4 to 5.6 | 1.4
5.7 to 6.0 | 1.5
Note that version 1.5+ requires PHP 7.1.3+ and czim/laravel-dataobject 2.0+.
## Changelog
[View the changelog](CHANGELOG.md).
## Installation
Via Composer
``` bash
$ composer require czim/laravel-jsonapi
```
Add the `JsonApiServiceProvider` to your `config/app.php`:
``` php
Czim\JsonApi\Providers\JsonApiServiceProvider::class,
```
Publish the configuration file.
``` bash
php artisan vendor:publish
```
### Exceptions
In your `App\Exceptions\Handler`, change the `render()` method like so:
```php
wantsJson()) {
return jsonapi_error($exception);
}
// ...
```
This will render exceptions thrown for all JSON-API (and JSON) requests as JSON-API error responses.
### Middleware
To enforce correct headers, add the `Czim\JsonApi\Http|Middleware\JsonApiHeaders` middleware
to the middleware group or relevant routes. You can do this by adding it to your `App\Http\Kernel` class:
```php
[
// ...
\Czim\JsonApi\Http\Middleware\RequireJsonApiHeader::class,
],
];
```
Note that this *will* block access to any consumers of your API that do not conform their HTTP header use
to the JSON-API standard.
## Documentation
### Request Data
#### Request Query String Data
JSON-API suggests passing in filter and page data using `GET` parameters, such as:
```
{API URL}?filter[id]=13&page[number]=2
```
This package offers tools for accessing this information in a standardized way:
Using the `jsonapi_query()` global helper function.
This returns the singleton instance of `Czim\JsonApi\Support\Request\RequestParser`.
```php
getFilter();
// Get a specific filter key value, if it is present (with a default fallback).
$id = jsonapi_query()->getFilterValue('id', 0);
// Get the page number.
$page = jsonapi_query()->getPageNumber();
```
You can ofcourse also instantiate the request parser yourself to access these methods:
```php
getFilterValue('id');
```
#### Request Body Data
For `PUT` and `POST` requests with JSON-API formatted body content, special FormRequests are provided to validate
and access request body data: `\Czim\JsonApi\Http\Requests\JsonApiRequest`.
For `POST` requests where `id` may be omitted while creating a resource, use `\Czim\JsonApi\Http\Requests\JsonApiRequest` instead.
These classes may be extended and used as any other FormRequest class in Laravel.
There are also a global help functions `jsonapi_request()` and `jsonapi_request_create()`,
that returns an instance of the relevant request class (and so mimics Laravel's `request()`).
Using this approach guarantees that requests are valid JSON-API by validating the input against a JSON Schema.
```php
data()->getRootType();
// Get validated data for the current request.
// This returns an instance of \Czim\JsonApi\Data\Root, which is a data object tree.
$root = jsonapi_request()->data();
// You can check what kind of resource data is contained.
if ( ! $root->hasSingleResourceData()) {
// In this case, the request would either have no "data" key,
// or it would contain NULL or an array of multiple resources.
} elseif ($root->hasMultipleResourceData()) {
// In this case, the request has a "data" key that contains an array of resources.
}
// Embedded data may be accessed as follows (for single resource).
$resourceId = $root->data->id;
$resourceType = $root->data->type;
$attributeValue = $root->data->attributes->name;
$relationType = $root->data->relationships['some-relationship']->data->type;
```
The request data tree for a single-resource request:
For more information on the data object tree, see [the Data classes](https://github.com/czim/laravel-jsonapi/tree/master/src/Data).
### Encoding
This package offers an encoder to generate valid JSON-API output for variable input content.
With some minor setup, it is possible to generate JSON output according to JSON-API specs for Eloquent models and errors.
`Eloquent` models, single, collected or paginated, will be serialized as JSON-API resources.
[More information on encoding](ENCODING.md) and configuring resources.
#### Custom Encoding & Transformation
To use your own transformers for specific class FQNs for the content to be encoded, map them in the `jsonapi.transform.map`
configuration key:
```php
[
\Your\ContentClassFqn\Here::class => \Your\TransformerClassFqn\Here::class,
],
```
This mapping will return the first-matched for content using `is_a()` checks.
More specific matches should be higher in the list.
As a last resort, you can always extend and/or rebind the `Czim\JsonApi\Encoder\Factories\TransformerFactory`
to provide your own transformers based on given content type.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## Credits
- [Coen Zimmerman][link-author]
- [All Contributors][link-contributors]
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
[ico-version]: https://img.shields.io/packagist/v/czim/laravel-jsonapi.svg?style=flat-square
[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square
[ico-downloads]: https://img.shields.io/packagist/dt/czim/laravel-jsonapi.svg?style=flat-square
[link-packagist]: https://packagist.org/packages/czim/laravel-jsonapi
[link-downloads]: https://packagist.org/packages/czim/laravel-jsonapi
[link-author]: https://github.com/czim
[link-contributors]: ../../contributors