swisnl / json-api-client
A PHP package for mapping remote JSON:API resources to Eloquent like models and collections.
Installs: 330 707
Dependents: 7
Suggesters: 0
Security: 0
Stars: 205
Watchers: 13
Forks: 24
Open Issues: 1
Requires
- php: ^7.4|^8.0
- ext-json: *
- illuminate/collections: ^8.0|^9.0|^10.0|^11.0
- illuminate/contracts: ^8.0|^9.0|^10.0|^11.0
- php-http/discovery: ^1.9
- psr/http-client: ^1.0
- psr/http-client-implementation: ^1.0
- psr/http-factory: ^1.0
- psr/http-factory-implementation: ^1.0
- psr/http-message: ^1.0|^2.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- guzzlehttp/guzzle: ^7.3
- php-http/mock-client: ^1.2
- phpunit/phpunit: ^9.5
Suggests
- swisnl/php-http-fixture-client: Allows for easily mocking API calls with fixtures in your tests
- 2.4.0
- dev-master / 2.3.x-dev
- 2.3.2
- 2.3.1
- 2.3.0
- 2.2.0
- 2.1.0
- 2.0.1
- 2.0.0
- 2.0.0-beta
- 1.x-dev
- 1.3.3
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.0
- 1.1.1
- 1.1.0
- 1.0.2
- 1.0.1
- 1.0.0
- 1.0.0-beta.3
- 1.0.0-beta.2
- 1.0.0-beta
- 0.20.0
- 0.19.0
- 0.18.0
- 0.17.0
- 0.16.0
- 0.15.0
- 0.14.0
- 0.13.0
- 0.12.1
- 0.12.0
- 0.11.0
- 0.10.3
- 0.10.2
- 0.10.1
- 0.10.0
- 0.9.0
- 0.8.0
- 0.7.5
- 0.7.4
- 0.7.3
- 0.7.2
- 0.7.1
- 0.7.0
- 0.6.0
- 0.5.0
- 0.4.0
- 0.3.2
- 0.3.1
- 0.3.0
- 0.2.3
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.1
- 0.1.0
- 0.0.3
- 0.0.2
- 0.0.1
- dev-feature/phpstan
- dev-test-less-deps-no-dicovery
- dev-test-less-deps
This package is auto-updated.
Last update: 2024-10-15 08:14:55 UTC
README
A PHP package for mapping remote JSON:API resources to Eloquent like models and collections.
💡 Before we start, please note that this library can only be used for JSON:API resources and requires some basic knowledge of the specification. If you are not familiar with {json:api}, please read the excellent blog by Björn Brala for a quick introduction.
Installation
ℹ️ Using Laravel? Take a look at swisnl/json-api-client-laravel for easy Laravel integration.
composer require swisnl/json-api-client
N.B. Make sure you have installed a PSR-18 HTTP Client and PSR-17 HTTP Factories before you install this package or install one at the same time e.g. composer require swisnl/json-api-client guzzlehttp/guzzle:^7.3
.
HTTP Client
We are decoupled from any HTTP messaging client with the help of PSR-18 HTTP Client and PSR-17 HTTP Factories.
This requires an extra package providing psr/http-client-implementation and psr/http-factory-implementation.
To use Guzzle 7, for example, simply require guzzlehttp/guzzle
:
composer require guzzlehttp/guzzle:^7.3
See HTTP Clients if you want to use your own HTTP client or use specific configuration options.
Getting started
You can simply create an instance of DocumentClient and use it in your class. Alternatively, you can create a repository.
use Swis\JsonApi\Client\DocumentClient; $client = DocumentClient::create(); $document = $client->get('https://cms.contentacms.io/api/recipes'); /** @var \Swis\JsonApi\Client\Collection&\Swis\JsonApi\Client\Item[] $collection */ $collection = $document->getData(); foreach ($collection as $item) { // Do stuff with the items }
Items
By default, all items are an instance of \Swis\JsonApi\Client\Item
.
The Item
provides a Laravel Eloquent-like base class.
You can define your own models by extending \Swis\JsonApi\Client\Item
or by implementing the \Swis\JsonApi\Client\Interfaces\ItemInterface
yourself.
This can be useful if you want to define, for example, hidden attributes, casts or get/set mutators.
If you use custom models, you must register them with the TypeMapper.
Relations
This package implements Laravel Eloquent-like relations. These relations provide a fluent interface to retrieve the related items. There are currently four relations available:
HasOneRelation
HasManyRelation
MorphToRelation
MorphToManyRelation
Please see the following example about defining the relationships:
use Swis\JsonApi\Client\Item; class AuthorItem extends Item { protected $type = 'author'; public function blogs() { return $this->hasMany(BlogItem::class); } } class BlogItem extends Item { protected $type = 'blog'; public function author() { return $this->hasOne(AuthorItem::class); } }
Naming support
Relations should be defined using camelCase methods. Related items can then be accessed via magic attributes in camelCase or snake_case or by using the explicit name you used when defining the relation.
Collections
This package uses Laravel Collections as a wrapper for item arrays.
Links
All objects that can have links (i.e. document, error, item and relationship) use Concerns/HasLinks
and thus have a getLinks
method that returns an instance of Links
.
This is a simple array-like object with key-value pairs which are in turn an instance of Link
or null
.
Example
Given the following JSON:
{ "links": { "self": "http://example.com/articles" }, "data": [{ "type": "articles", "id": "1", "attributes": { "title": "JSON:API paints my bikeshed!" }, "relationships": { "author": { "data": { "type": "people", "id": "9" }, "links": { "self": "http://example.com/articles/1/author" } } }, "links": { "self": "http://example.com/articles/1" } }] }
You can get the links this way:
/** @var $document \Swis\JsonApi\Client\Document */ // Document links $links = $document->getLinks(); echo $links->self->getHref(); // http://example.com/articles // Item links $links = $document->getData()->getLinks(); echo $links->self->getHref(); // http://example.com/articles/1 // Relationship links $links = $document->getData()->author()->getLinks(); echo $links->self->getHref(); // http://example.com/articles/1/author
Meta
All objects that can have meta information (i.e. document, error, item, jsonapi, link and relationship) use Concerns/HasMeta
and thus have a getMeta
method that returns an instance of Meta
.
This is a simple array-like object with key-value pairs.
Example
Given the following JSON:
{ "links": { "self": { "href": "http://example.com/articles/1", "meta": { "foo": "bar" } } }, "data": { "type": "articles", "id": "1", "attributes": { "title": "JSON:API paints my bikeshed!" }, "relationships": { "author": { "data": { "type": "people", "id": "9" }, "meta": { "written_at": "2019-07-16T13:47:26" } } }, "meta": { "copyright": "Copyright 2015 Example Corp." } }, "meta": { "request_id": "a77ab2b4-7132-4782-8b5e-d94ebaff6e13" } }
You can get the meta this way:
/** @var $document \Swis\JsonApi\Client\Document */ // Document meta $meta = $document->getMeta(); echo $meta->request_id; // a77ab2b4-7132-4782-8b5e-d94ebaff6e13 // Link meta $meta = $document->getLinks()->self->getMeta(); echo $meta->foo; // bar // Item meta $meta = $document->getData()->getMeta(); echo $meta->copyright; // Copyright 2015 Example Corp. // Relationship meta $meta = $document->getData()->author()->getMeta(); echo $meta->written_at; // 2019-07-16T13:47:26
TypeMapper
All custom models must be registered with the TypeMapper
.
This TypeMapper
maps, as the name suggests, JSON:API types to custom items.
Repository
For convenience, this package includes a basic repository with several methods to work with resources.
You can create a repository for each of the endpoints you use based on \Swis\JsonApi\Client\Repository
.
This repository then uses standard CRUD endpoints for all its actions.
class BlogRepository extends \Swis\JsonApi\Client\Repository { protected $endpoint = 'blogs'; }
The above repository will have a method for all CRUD-actions. If you work with a read-only API and don't want to have all actions, you can build your own repository by extending \Swis\JsonApi\Client\BaseRepository
and including just the actions/traits you need.
use Swis\JsonApi\Client\Actions\FetchMany; use Swis\JsonApi\Client\Actions\FetchOne; class BlogRepository extends \Swis\JsonApi\Client\BaseRepository { use FetchMany; use FetchOne; protected $endpoint = 'blogs'; }
If this repository (pattern) doesn't fit your needs, you can create your own implementation using the clients provided by this package.
Request parameters
All methods provided by the repository take extra parameters that will be appended to the url. This can be used, among other things, to add include and/or pagination parameters:
$repository = new BlogRepository(); $repository->all(['include' => 'author', 'page' => ['limit' => 15, 'offset' => 0]]);
ItemHydrator
The ItemHydrator
can be used to fill/hydrate an item and its relations using an associative array with attributes.
This is useful if you would like to hydrate an item with POST data from your request:
$typeMapper = new TypeMapper(); $itemHydrator = new ItemHydrator($typeMapper); $blogRepository = new BlogRepository(DocumentClient::create($typeMapper), new DocumentFactory()); $item = $itemHydrator->hydrate( $typeMapper->getMapping('blog'), request()->all(['title', 'author', 'date', 'content', 'tags']), request()->id ); $blogRepository->save($item);
Relations
The ItemHydrator
also hydrates (nested) relations.
A relation must explicitly be listed on the item in the $availableRelations
array in order to be hydrated.
If we take the above example, we can use the following attributes array to hydrate a new blog item:
$attributes = [ 'title' => 'Introduction to JSON:API', 'author' => [ 'id' => 'f1a775ef-9407-40ba-93ff-7bd737888dc6', 'name' => 'Björn Brala', 'homepage' => 'https://github.com/bbrala', ], 'co-author' => null, 'date' => '2018-12-02 15:26:32', 'content' => 'JSON:API was originally drafted in May 2013 by Yehuda Katz...', 'media' => [], 'tags' => [ 1, 15, 56, ], ]; $itemDocument = $itemHydrator->hydrate($typeMapper->getMapping('blog'), $attributes); echo json_encode($itemDocument, JSON_PRETTY_PRINT); { "data": { "type": "blog", "attributes": { "title": "Introduction to JSON:API", "date": "2018-12-02 15:26:32", "content": "JSON:API was originally drafted in May 2013 by Yehuda Katz..." }, "relationships": { "author": { "data": { "type": "author", "id": "f1a775ef-9407-40ba-93ff-7bd737888dc6" } }, "co-author": { "data": null }, "media": { "data": [] }, "tags": { "data": [{ "type": "tag", "id": "1" }, { "type": "tag", "id": "15" }, { "type": "tag", "id": "56" }] } } }, "included": [{ "type": "author", "id": "f1a775ef-9407-40ba-93ff-7bd737888dc6", "attributes": { "name": "Björn Brala", "homepage": "https://github.com/bbrala" } }] }
As you can see in this example, relations can be hydrated by id, or by an associative array with an id and more attributes.
If the item is hydrated using an associative array, it will be included in the resulting json unless setOmitIncluded(true)
is called on the relation.
You can unset a relation by passing null
for singular relations or an empty array for plural relations.
N.B. Morph relations require a 'type' attribute to be present in the data in order to know which type of item should be created.
Handling errors
A request can fail due to several reasons and how this is handled depends on what happened.
If the DocumentClient
encounters an error there are basically three options.
Non 2xx request without body
If a response does not have a successful status code (2xx) and does not have a body, the DocumentClient
(and therefore also the Repository
) will return an instance of InvalidResponseDocument
.
Non 2xx request with invalid JSON:API body
If a response does not have a successful status code (2xx) and does have a body, it is parsed as if it's a JSON:API document.
If the response can not be parsed as such document, a ValidationException
will be thrown.
Non 2xx request with valid JSON:API body
If a response does not have a successful status code (2xx) and does have a body, it is parsed as if it's a JSON:API document.
In this case the DocumentClient
(and therefore also the Repository
) will return an instance of Document
.
This document contains the errors from the response, assuming the server responded with errors.
Checking for errors
Based on the above rules you can check for errors like this:
$document = $repository->all(); if ($document instanceof InvalidResponseDocument || $document->hasErrors()) { // do something with errors }
Clients
This package offers two clients; DocumentClient
and Client
.
DocumentClient
This is the client that you would generally use e.g. the repository uses this client internally.
Per the JSON:API spec, all requests and responses are documents.
Therefore, this client always expects a \Swis\JsonApi\Client\Interfaces\DocumentInterface
as input when posting data and always returns this same interface.
This can be a plain Document
when there is no data, an ItemDocument
for an item, a CollectionDocument
for a collection or an InvalidResponseDocument
when the server responds with a non 2xx response.
The DocumentClient
follows the following steps internally:
- Send the request using your HTTP client;
- Use
ResponseParser
to parse and validate the response; - Create the correct document instance;
- Hydrate every item by using the item model registered with the
TypeMapper
or a\Swis\JsonApi\Client\Item
as fallback; - Hydrate all relationships;
- Add meta data to the document such as errors, links and meta.
Client
This client is a more low level client and can be used, for example, for posting binary data such as images.
It can take everything your request factory takes as input data and returns the 'raw' \Psr\Http\Message\ResponseInterface
.
It does not parse or validate the response or hydrate items!
DocumentFactory
The DocumentClient
requires ItemDocumentInterface
instances when creating or updating resources.
Such documents can easily be created using the DocumentFactory
by giving it a DataInterface
instance.
This can be an ItemInterface
, usually created by the ItemHydrator, or a Collection
.
HTTP Clients
By default the Client
uses php-http/discovery to find an available HTTP client, request factory and stream factory so you don't have to setup those yourself.
You can also specify your own HTTP client, request factory or stream factory.
This is a perfect way to add extra options to your HTTP client or register a mock HTTP client for your tests:
if (app()->environment('testing')) { $httpClient = new \Swis\Http\Fixture\Client( new \Swis\Http\Fixture\ResponseBuilder('/path/to/fixtures') ); } else { $httpClient = new \GuzzleHttp\Client( [ 'http_errors' => false, 'timeout' => 2, ] ); } $typeMapper = new TypeMapper(); $client = DocumentClient::create($typeMapper, $httpClient); $document = $client->get('https://cms.contentacms.io/api/recipes');
N.B. This example uses our swisnl/php-http-fixture-client when in testing environment. This package allows you to easily mock requests with static fixtures. Definitely worth a try!
Advanced usage
If you don't like to use the supplied repository or clients, you can also parse a 'raw' \Psr\Http\Message\ResponseInterface
or a simple json string using the Parsers\ResponseParser
or Parser\DocumentParser
respectively.
Change log
Please see CHANGELOG for more information on what has changed recently.
Testing
composer test
Contributing
Please see CONTRIBUTING and CODE_OF_CONDUCT for details.
Security
If you discover any security related issues, please email security@swis.nl instead of using the issue tracker.
License
The MIT License (MIT). Please see License File for more information.
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
SWIS ❤️ Open Source
SWIS is a web agency from Leiden, the Netherlands. We love working with open source software.