Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dogado-group/json-api-client
Abstract client side php implementation of the JSON:API protocol.
https://github.com/dogado-group/json-api-client
client dogado json json-api php php74 php8 psr-17 psr-18
Last synced: 24 days ago
JSON representation
Abstract client side php implementation of the JSON:API protocol.
- Host: GitHub
- URL: https://github.com/dogado-group/json-api-client
- Owner: dogado-group
- License: mit
- Created: 2021-05-21T09:31:54.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2022-10-17T10:57:39.000Z (about 2 years ago)
- Last Synced: 2024-10-01T18:10:47.521Z (about 1 month ago)
- Topics: client, dogado, json, json-api, php, php74, php8, psr-17, psr-18
- Language: PHP
- Homepage: https://www.dogado.de
- Size: 46.9 KB
- Stars: 2
- Watchers: 4
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# Abstract client side php implementation of the JSON:API protocol.
[](https://github.com/dogado-group/json-api-client/actions/workflows/phpunit.yml)
[](https://coveralls.io/github/dogado-group/json-api-client?branch=main)
[](https://packagist.org/packages/dogado/json-api-client)
[](https://packagist.org/packages/dogado/json-api-client)
[](https://packagist.org/packages/dogado/json-api-client)
[](https://packagist.org/packages/dogado/json-api-client)
## Installation
```sh
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.
```sh
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
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.
```php
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
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
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.
```php
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
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
- [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
The MIT License (MIT). Please see [License File](LICENSE) for more information.