PHPackages                             dogado/json-api-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. dogado/json-api-client

ActiveLibrary[API Development](/categories/api)

dogado/json-api-client
======================

Abstract client side php implementation of the JSON:API protocol.

v3.0.0(4y ago)26.8kMITPHPPHP ^8.0

Since May 25Pushed 3y ago3 watchersCompare

[ Source](https://github.com/dogado-group/json-api-client)[ Packagist](https://packagist.org/packages/dogado/json-api-client)[ Docs](https://github.com/dogado-group/json-api-client)[ RSS](/packages/dogado-json-api-client/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (5)Dependencies (8)Versions (8)Used By (0)

Abstract client side php implementation of the JSON:API protocol.
=================================================================

[](#abstract-client-side-php-implementation-of-the-jsonapi-protocol)

[![phpunit](https://github.com/dogado-group/json-api-client/actions/workflows/phpunit.yml/badge.svg)](https://github.com/dogado-group/json-api-client/actions/workflows/phpunit.yml)[![Coverage Status](https://camo.githubusercontent.com/634b0cd5414a67f365c127a994e875fe84d474929fe08a13a268f5ee0c538b67/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f646f6761646f2d67726f75702f6a736f6e2d6170692d636c69656e742f62616467652e7376673f6272616e63683d6d61696e)](https://coveralls.io/github/dogado-group/json-api-client?branch=main)[![Total Downloads](https://camo.githubusercontent.com/f735e53db2a6963a0bc8822958ed7c67cffd57bbad9e73f11322b12a9bdc0a0c/68747470733a2f2f706f7365722e707567782e6f72672f646f6761646f2f6a736f6e2d6170692d636c69656e742f646f776e6c6f616473)](https://packagist.org/packages/dogado/json-api-client)[![Latest Stable Version](https://camo.githubusercontent.com/0fad3a8d23a5e4ce42a6fa241ae5e62534ab0c4d1e4136a74f327a57e341619e/68747470733a2f2f706f7365722e707567782e6f72672f646f6761646f2f6a736f6e2d6170692d636c69656e742f762f737461626c65)](https://packagist.org/packages/dogado/json-api-client)[![Latest Unstable Version](https://camo.githubusercontent.com/8d9a21f7b81b99cd79d1e1b00af7cd5b3918e4e3a3f4da829177fc82a82d10f2/68747470733a2f2f706f7365722e707567782e6f72672f646f6761646f2f6a736f6e2d6170692d636c69656e742f762f756e737461626c652e706e67)](https://packagist.org/packages/dogado/json-api-client)[![License](https://camo.githubusercontent.com/86dbe2143b18c017aee317918cd11ec6dfc67b3fa1478d15b0daa4f4c8659e47/68747470733a2f2f706f7365722e707567782e6f72672f646f6761646f2f6a736f6e2d6170692d636c69656e742f6c6963656e7365)](https://packagist.org/packages/dogado/json-api-client)

Installation
------------

[](#installation)

```
composer require dogado/json-api-client
```

It's recommended to install `guzzlehttp/guzzle` version `^7.0` as http-client and `http-interop/http-factory-guzzle` for [PSR-17](https://www.php-fig.org/psr/psr-17/) compatible factories.

```
composer require guzzlehttp/guzzle http-interop/http-factory-guzzle
```

You can also use any other HTTP client which implements [PSR-18](https://www.php-fig.org/psr/psr-18/).

Usage
-----

[](#usage)

First you should read the docs of [dogado/json-api-common](https://github.com/dogado-group/json-api-common/tree/main/docs) where all basic structures will be explained.

Your API client is an instance of `Dogado\JsonApi\Client\JsonApiClient`, which requires a [PSR-18](https://www.php-fig.org/psr/psr-18/) HTTP client (`Psr\Http\Client\ClientInterface`) to execute requests.

```
use Dogado\JsonApi\Client\JsonApiClient;
use Dogado\JsonApi\Client\Factory\RequestFactory;
use Dogado\JsonApi\Client\Validator\ResponseValidator;

$client = new JsonApiClient(
    $httpClient, // instance of Psr\Http\Client\ClientInterface
    $psrRequestFactory, // instance of Psr\Http\Message\RequestFactoryInterface
    $streamFactory, // instance of Psr\Http\Message\StreamFactoryInterface
    $serializer, // instance of Dogado\JsonApi\Serializer\DocumentSerializerInterface
    $responseFactory, // instance of Dogado\JsonApi\Client\Response\ResponseFactoryInterface
    $authMiddleware // optional instance of Dogado\JsonApi\Client\Middleware\AuthenticationMiddlewareInterface. See docs below.
);

$baseUrl = new Uri('http://example.com/api');
$requestFactory = new RequestFactory($baseUrl);

$request = $requestFactory->createGetRequest(new Uri('/myResource/1')); // will fetch the resource at http://example.com/api/myResource/1
$response = $client->execute($request);

// OPTIONAL: Validate the response to match your needs. See the ResponseValidator class for all assertion methods
(new ResponseValidator())->assertResourcesMatchTypeAndContainIds($response, 'myResource');

$document = $response->document();
$myResource = $document->data()->first(); // the resource fetched by this request
$myIncludedResources = $document->included()->all(); // the included resources fetched with the include parameter
```

### Action Pattern

[](#action-pattern)

In most cases it's easier to capsule request scenarios into single classes since every request has its own requirements. In this package this is called `Action`. To make things easier, we already defined an `AbstractAction` class under the `Dogado\JsonApi\Client\Action` namespace. An example how to create such an action can be found [in the tests](./tests/Action/DummyAction.php).

When fetching resources in actions it's also very common to filter, paginate and sort. To define these options within Actions, there are multiple Traits you can use, defined in the same namespace as the `AbstractAction` class.

### Authentication

[](#authentication)

When using a JSON:API client to access a server application you will probably need to be authenticated. As this a common use case, this client offers native support for authentication as so called "AuthenticationMiddleware" represented by an interface. The client provides a native set of authentication mechanisms: OAuth2 client credentials and HTTP basic auth, but you can create a custom middleware yourself based on the `AuthenticationMiddlewareInterface` if that doesn't fit your needs or feel free to create a [pull request](https://github.com/dogado-group/json-api-client/pulls) to add more authentications.

```
use Dogado\JsonApi\Serializer\Deserializer;
use Dogado\JsonApi\Serializer\Serializer;
use Dogado\JsonApi\Client\JsonApiClient;
use Dogado\JsonApi\Client\Response\ResponseFactory;
use Dogado\JsonApi\Client\Middleware\AuthenticationMiddleware;

/** @var Psr\Http\Client\ClientInterface $httpClient */
/** @var Psr\Http\Message\RequestFactoryInterface $requestFactory */
/** @var Psr\Http\Message\StreamFactoryInterface $streamFactory */
/** @var Psr\Http\Message\UriFactoryInterface $uriFactory */

// define which authentication you want to use (you can also leave the middleware `null` in order to use no authentication)
$authenticationMiddleware = new AuthenticationMiddleware();
$client = new JsonApiClient(
    $httpClient,
    $requestFactory,
    $streamFactory,
    new Serializer(),
    new ResponseFactory(
        new Deserializer()
    ),
    $authenticationMiddleware
);

###### HTTP basic auth
use Dogado\JsonApi\Client\Model\BasicCredentials;
$authenticationMiddleware->setBasicCredentials(new BasicCredentials('username', 'password'));

###### OAuth 2 client credentials
use Dogado\JsonApi\Client\Factory\Oauth2\CredentialFactory;
use Dogado\JsonApi\Client\Service\OAuth2Authenticator;
use Dogado\JsonApi\Client\Exception\Oauth2\AuthenticationException;

# the Authenticator class also allows you to overload the HTTP client and the auth storage factory it uses
$authenticator = new OAuth2Authenticator($httpClient, $requestFactory, $streamFactory, new CredentialFactory());
try {
    $oauth2Credentials = $authenticator->withClientCredentials($uriFactory->createUri('https://server.local/oauth/token'), 'Client-ID', 'Client-Secret');
    $authenticationMiddleware->setOAuth2Credentials($oauth2Credentials);
} catch (AuthenticationException $e) {
    // escalate any errors accordingly
}
```

#### OAuth2

[](#oauth2)

The `AuthenticationMiddleware` class requires a `Dogado\JsonApi\Client\Model\OAuth2Credentials` instance which contains an access token, the token type and the expiration date. You can either create an instance yourself and insert the required data or use the `Dogado\JsonApi\Client\Service\OAuth2Authenticator` class to generate them.

Please cache the `OAuth2Credentials` instance as long as the method `isExpired` is not `true`, to prevent unnecessary authentication calls.

As the authentication endpoint does not follow the JSON:API protocol, it also throws no JSON:API specific errors or exceptions. The only relevant errors are variations of the `Dogado\JsonApi\Client\Exception\Oauth2\AuthenticationException` class which differentiates between error message and code. Such an exception instance also contains the plain response as `Psr\Http\Message\ResponseInterface` to have more context to an error.

Credits
-------

[](#credits)

- [Chris Döhring](https://github.com/chris-doehring)
- [Philipp Marien](https://github.com/pmarien)
- [eosnewmedia team](https://github.com/eosnewmedia)

This package contains code taken from [enm/json-api-client](https://github.com/eosnewmedia/JSON-API-Client).

License
-------

[](#license)

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

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity24

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 94.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~33 days

Total

5

Last Release

1734d ago

Major Versions

v1.1.0 → v2.0.02021-07-12

v2.0.0 → v3.0.02021-10-04

PHP version history (2 changes)v1.0.0PHP ^7.4 || ^8.0

v1.1.0PHP ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/8f25bd8f4a5f0287916cd551d6d29410527d9fa8a70d1a9f6705ac8d4e4b1a04?d=identicon)[chris-doehring](/maintainers/chris-doehring)

---

Top Contributors

[![chris-doehring](https://avatars.githubusercontent.com/u/6341536?v=4)](https://github.com/chris-doehring "chris-doehring (16 commits)")[![stixxx2k](https://avatars.githubusercontent.com/u/17484476?v=4)](https://github.com/stixxx2k "stixxx2k (1 commits)")

---

Tags

clientdogadojsonjson-apiphpphp74php8psr-17psr-18JSON-APIdogado

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/dogado-json-api-client/health.svg)

```
[![Health](https://phpackages.com/badges/dogado-json-api-client/health.svg)](https://phpackages.com/packages/dogado-json-api-client)
```

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)[mollie/mollie-api-php

Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.

60216.0M85](/packages/mollie-mollie-api-php)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[getbrevo/brevo-php

Official Brevo provided RESTFul API V3 php library

1003.9M50](/packages/getbrevo-brevo-php)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6942.5M421](/packages/drupal-core-recommended)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35789.4k2](/packages/telnyx-telnyx-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)