Human-friendly library to implement JSON:API without needing to know the specification.
MIT License
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.
Use Composer require to get the latest stable version:
composer require alsvanzelf/jsonapi
The library supports, and is is tested on, php versions 5.6, 7 and 8.
If you used v1 of this library, see UPGRADE_1_TO_2.md on how to upgrade.
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
}
}
}
use alsvanzelf\jsonapi\CollectionDocument;
use alsvanzelf\jsonapi\objects\ResourceObject;
$arthur = new ResourceObject('user', 1);
$ford = new ResourceObject('user', 2);
$zaphod = new ResourceObject('user', 42);
$heartOfGold = new ResourceObject('starship', 2001);
$arthur->add('name', 'Arthur Dent');
$ford->add('name', 'Ford Prefect');
$zaphod->add('name', 'Zaphod Beeblebrox');
$heartOfGold->add('name', 'Heart of Gold');
$zaphod->addRelationship('drives', $heartOfGold);
$users = [$arthur, $ford, $zaphod];
$document = CollectionDocument::fromResources(...$users);
$document->sendResponse();
Which will result in:
{
"jsonapi": {
"version": "1.1"
},
"data": [
{
"type": "user",
"id": "1",
"attributes": {
"name": "Arthur Dent"
}
},
{
"type": "user",
"id": "2",
"attributes": {
"name": "Ford Prefect"
}
},
{
"type": "user",
"id": "42",
"attributes": {
"name": "Zaphod Beeblebrox"
},
"relationships": {
"drives": {
"data": {
"type": "starship",
"id": "2001"
}
}
}
}
],
"included": [
{
"type": "starship",
"id": "2001",
"attributes": {
"name": "Heart of Gold"
}
}
]
}
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": 137,
"trace": []
}
}
]
}
This can be useful for development. For production usage, you can better construct an ErrorsDocument
with only specific values.
The Atomic Operations extension and the Cursor Pagination profile come packaged along. Any 3rd party of self-made extension can be applied with:
use alsvanzelf\jsonapi\ResourceDocument;
use alsvanzelf\jsonapi\interfaces\ExtensionInterface;
class ExampleExtension implements ExtensionInterface {
public function getOfficialLink() {
return 'https://example.org/extension-documentation';
}
public function getNamespace() {
return 'foo';
}
}
$document = new ResourceDocument('user', 42);
$document->add('name', 'Zaphod Beeblebrox');
$extension = new ExampleExtension();
$document->applyExtension($extension);
$document->addExtensionMember($extension, 'bar', 'baz');
$document->sendResponse();
Which will result in:
{
"foo:bar": "baz",
"jsonapi": {
"version": "1.1",
"ext": [
"https://example.org/extension-documentation"
]
},
"data": {
"type": "user",
"id": "42",
"attributes": {
"name": "Zaphod Beeblebrox"
}
}
}
A similar flow can be used for profiles.
Examples for all kind of responses are in the /examples directory.
This library supports v1.1 of the JSON:API specification.
It has support for generating & sending documents with:
Also there's tools to help processing of incoming requests:
Next to custom extensions/profiles, the following official extensions/profiles are included:
Plans for the future include:
If you use the library, please ask questions or share what can be improved by creating an issue.
For bugs issues or Pull Requests are welcome!