Skip to content
Human-friendly library to implement JSON:API without needing to know the specification.
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Merge branch 'master' into relation-free-format Mar 3, 2019
script allow php7 throwables to build ErrorsDocuments from Feb 9, 2019
src prevent calling non-existing methods on a ResourceIdentifierObject Mar 23, 2019
tests prevent calling non-existing methods on a ResourceIdentifierObject Mar 23, 2019
.editorconfig test all methods throwing exceptions Feb 6, 2019
.gitignore
.scrutinizer.yml
.travis.yml allow php7 throwables to build ErrorsDocuments from Feb 9, 2019
LICENSE Initial commit May 26, 2015
README.md more badges Mar 23, 2019
UPGRADE_1_TO_2.md bump the supported spec version Mar 3, 2019
composer.json
composer.lock bump php version, fix tests for phpunit deprecation Feb 6, 2019
phpunit.xml make sure to catch all levels of errors Feb 23, 2019
phpunitWithCodeCoverage.xml run code coverage testing with scrunitize Mar 23, 2019

README.md

jsonapi Build Status Scrutinizer Code Quality Code Coverage

A simple and human-friendly library for api servers (php serving json).

It allows you to generate json output according to the JSON:API v1.1 standard, while being easy to understand for people without knowledge of the jsonapi standard.

The JSON:API standard makes it easy for clients to fetch multiple resources in one call and understand the relations between them. Read more about it at jsonapi.org.

Installation

Use Composer require to get the latest stable version:

composer require alsvanzelf/jsonapi

Upgrading from v1

If you used v1 of this library, see UPGRADE_1_TO_2.md on how to upgrade.

Getting started

A small resource example

use alsvanzelf\jsonapi\ResourceDocument;

$document = new ResourceDocument($type='user', $id=42);
$document->add('name', 'Zaphod Beeblebrox');
$document->add('heads', 2);
$document->sendResponse();

Which will result in:

{
	"jsonapi": {
		"version": "1.1"
	},
	"data": {
		"type": "user",
		"id": "42",
		"attributes": {
			"name": "Zaphod Beeblebrox",
			"heads": 2
		}
	}
}

A collection of resources

use alsvanzelf\jsonapi\CollectionDocument;

$document = new CollectionDocument();
$document->add('user', 42, ['name' => 'Zaphod Beeblebrox']);
$document->add('user', 1, ['name' => 'Ford Prefect']);
$document->add('user', 2, ['name' => 'Arthur Dent']);
$document->sendResponse();

Which will result in:

{
	"jsonapi": {
		"version": "1.1"
	},
	"data": [
		{
			"type": "user",
			"id": "42",
			"attributes": {
				"name": "Zaphod Beeblebrox"
			}
		},
		{
			"type": "user",
			"id": "1",
			"attributes": {
				"name": "Ford Prefect"
			}
		},
		{
			"type": "user",
			"id": "2",
			"attributes": {
				"name": "Arthur Dent"
			}
		}
	]
}

Turning an exception into jsonapi

use alsvanzelf\jsonapi\ErrorsDocument;

$exception = new Exception('That is not valid', 422);

$document = ErrorsDocument::fromException($exception);
$document->sendResponse();

Which will result in:

{
	"jsonapi": {
		"version": "1.1"
	},
	"errors": [
		{
			"status": "422",
			"code": "Exception",
			"meta": {
				"class": "Exception",
				"message": "That is not valid",
				"code": 422,
				"file": "README.md",
				"line": 107,
				"trace": []
			}
		}
	]
}

Examples for all kind of responses are in the /examples directory.

Features

This library supports v1.1 of the JSON:API specification.

It has support for generating & sending documents with:

  • single resources
  • resource collections
  • to-one and to-many relationships
  • errors (easily turning exceptions into jsonapi output)
  • v1.1 extensions via profiles
  • v1.1 @-members for JSON-LD and others

Next to custom extensions, the following official extensions are included:

Plans for the future include:

  • parse request options: sparse fields, sorting, pagination, filtering (#44)
  • parse requests for creating, updating and deleting resources and relationships (#5)

Contributing

Pull Requests or issues are welcome!

Licence

MIT

You can’t perform that action at this time.