{"id":15296400,"url":"https://github.com/dogado-group/json-api-client","last_synced_at":"2025-07-24T00:04:27.573Z","repository":{"id":46601434,"uuid":"369484333","full_name":"dogado-group/json-api-client","owner":"dogado-group","description":"Abstract client side php implementation of the JSON:API protocol.","archived":false,"fork":false,"pushed_at":"2022-10-17T10:57:39.000Z","size":48,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-18T14:55:54.030Z","etag":null,"topics":["client","dogado","json","json-api","php","php74","php8","psr-17","psr-18"],"latest_commit_sha":null,"homepage":"https://www.dogado.de","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dogado-group.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null}},"created_at":"2021-05-21T09:31:54.000Z","updated_at":"2023-01-10T19:27:31.000Z","dependencies_parsed_at":"2022-08-21T11:20:10.681Z","dependency_job_id":null,"html_url":"https://github.com/dogado-group/json-api-client","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/dogado-group/json-api-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dogado-group%2Fjson-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dogado-group%2Fjson-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dogado-group%2Fjson-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dogado-group%2Fjson-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dogado-group","download_url":"https://codeload.github.com/dogado-group/json-api-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dogado-group%2Fjson-api-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266770247,"owners_count":23981528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","dogado","json","json-api","php","php74","php8","psr-17","psr-18"],"created_at":"2024-09-30T18:10:22.018Z","updated_at":"2025-07-24T00:04:27.058Z","avatar_url":"https://github.com/dogado-group.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Abstract client side php implementation of the JSON:API protocol.\n\n[![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)\n[![Coverage Status](https://coveralls.io/repos/github/dogado-group/json-api-client/badge.svg?branch=main)](https://coveralls.io/github/dogado-group/json-api-client?branch=main)\n[![Total Downloads](https://poser.pugx.org/dogado/json-api-client/downloads)](https://packagist.org/packages/dogado/json-api-client)\n[![Latest Stable Version](https://poser.pugx.org/dogado/json-api-client/v/stable)](https://packagist.org/packages/dogado/json-api-client)\n[![Latest Unstable Version](https://poser.pugx.org/dogado/json-api-client/v/unstable.png)](https://packagist.org/packages/dogado/json-api-client)\n[![License](https://poser.pugx.org/dogado/json-api-client/license)](https://packagist.org/packages/dogado/json-api-client)\n\n## Installation\n\n```sh\ncomposer require dogado/json-api-client\n```\n\nIt'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.\n\n```sh\ncomposer require guzzlehttp/guzzle http-interop/http-factory-guzzle\n```\n\nYou can also use any other HTTP client which implements [PSR-18](https://www.php-fig.org/psr/psr-18/).\n\n## Usage\n\nFirst 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.\n\nYour 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.\n\n```php\nuse Dogado\\JsonApi\\Client\\JsonApiClient;\nuse Dogado\\JsonApi\\Client\\Factory\\RequestFactory;\nuse Dogado\\JsonApi\\Client\\Validator\\ResponseValidator;\n\n$client = new JsonApiClient(\n    $httpClient, // instance of Psr\\Http\\Client\\ClientInterface\n    $psrRequestFactory, // instance of Psr\\Http\\Message\\RequestFactoryInterface\n    $streamFactory, // instance of Psr\\Http\\Message\\StreamFactoryInterface\n    $serializer, // instance of Dogado\\JsonApi\\Serializer\\DocumentSerializerInterface\n    $responseFactory, // instance of Dogado\\JsonApi\\Client\\Response\\ResponseFactoryInterface\n    $authMiddleware // optional instance of Dogado\\JsonApi\\Client\\Middleware\\AuthenticationMiddlewareInterface. See docs below.\n);\n\n$baseUrl = new Uri('http://example.com/api');\n$requestFactory = new RequestFactory($baseUrl);\n\n$request = $requestFactory-\u003ecreateGetRequest(new Uri('/myResource/1')); // will fetch the resource at http://example.com/api/myResource/1\n$response = $client-\u003eexecute($request);\n\n// OPTIONAL: Validate the response to match your needs. See the ResponseValidator class for all assertion methods\n(new ResponseValidator())-\u003eassertResourcesMatchTypeAndContainIds($response, 'myResource');\n\n$document = $response-\u003edocument();\n$myResource = $document-\u003edata()-\u003efirst(); // the resource fetched by this request\n$myIncludedResources = $document-\u003eincluded()-\u003eall(); // the included resources fetched with the include parameter\n```\n\n### Action Pattern\n\nIn most cases it's easier to capsule request scenarios into single classes since every request has its own requirements.\nIn this package this is called `Action`. To make things easier, we already defined an `AbstractAction` class under the\n`Dogado\\JsonApi\\Client\\Action` namespace. An example how to create such an action can be found\n[in the tests](./tests/Action/DummyAction.php).\n\nWhen fetching resources in actions it's also very common to filter, paginate and sort. To define these options within Actions,\nthere are multiple Traits you can use, defined in the same namespace as the `AbstractAction` class.\n\n### Authentication\n\nWhen using a JSON:API client to access a server application you will probably need to be authenticated. As this a common\nuse case, this client offers native support for authentication as so called \"AuthenticationMiddleware\" represented by\nan interface. The client provides a native set of authentication mechanisms: OAuth2 client credentials and HTTP basic\nauth, but you can create a custom middleware yourself based on the `AuthenticationMiddlewareInterface` if that doesn't\nfit your needs or feel free to create a [pull request](https://github.com/dogado-group/json-api-client/pulls) to add\nmore authentications. \n\n```php\nuse Dogado\\JsonApi\\Serializer\\Deserializer;\nuse Dogado\\JsonApi\\Serializer\\Serializer;\nuse Dogado\\JsonApi\\Client\\JsonApiClient;\nuse Dogado\\JsonApi\\Client\\Response\\ResponseFactory;\nuse Dogado\\JsonApi\\Client\\Middleware\\AuthenticationMiddleware;\n\n/** @var Psr\\Http\\Client\\ClientInterface $httpClient */\n/** @var Psr\\Http\\Message\\RequestFactoryInterface $requestFactory */\n/** @var Psr\\Http\\Message\\StreamFactoryInterface $streamFactory */\n/** @var Psr\\Http\\Message\\UriFactoryInterface $uriFactory */\n\n// define which authentication you want to use (you can also leave the middleware `null` in order to use no authentication)\n$authenticationMiddleware = new AuthenticationMiddleware();\n$client = new JsonApiClient(\n    $httpClient,\n    $requestFactory,\n    $streamFactory,\n    new Serializer(),\n    new ResponseFactory(\n        new Deserializer()\n    ),\n    $authenticationMiddleware\n);\n\n###### HTTP basic auth\nuse Dogado\\JsonApi\\Client\\Model\\BasicCredentials;\n$authenticationMiddleware-\u003esetBasicCredentials(new BasicCredentials('username', 'password'));\n\n###### OAuth 2 client credentials\nuse Dogado\\JsonApi\\Client\\Factory\\Oauth2\\CredentialFactory;\nuse Dogado\\JsonApi\\Client\\Service\\OAuth2Authenticator;\nuse Dogado\\JsonApi\\Client\\Exception\\Oauth2\\AuthenticationException;\n\n# the Authenticator class also allows you to overload the HTTP client and the auth storage factory it uses\n$authenticator = new OAuth2Authenticator($httpClient, $requestFactory, $streamFactory, new CredentialFactory());\ntry {\n    $oauth2Credentials = $authenticator-\u003ewithClientCredentials($uriFactory-\u003ecreateUri('https://server.local/oauth/token'), 'Client-ID', 'Client-Secret');\n    $authenticationMiddleware-\u003esetOAuth2Credentials($oauth2Credentials);\n} catch (AuthenticationException $e) {\n    // escalate any errors accordingly\n}\n```\n\n#### OAuth2\nThe `AuthenticationMiddleware` class requires a `Dogado\\JsonApi\\Client\\Model\\OAuth2Credentials` instance which\ncontains an access token, the token type and the expiration date. You can either create an instance yourself and insert\nthe required data or use the `Dogado\\JsonApi\\Client\\Service\\OAuth2Authenticator` class to generate them.\n\nPlease cache the `OAuth2Credentials` instance as long as the method `isExpired` is not `true`, to prevent unnecessary\nauthentication calls.\n\nAs the authentication endpoint does not follow the JSON:API protocol, it also throws no JSON:API specific errors or\nexceptions. The only relevant errors are variations of the\n`Dogado\\JsonApi\\Client\\Exception\\Oauth2\\AuthenticationException` class which differentiates between error message\nand code. Such an exception instance also contains the plain response as `Psr\\Http\\Message\\ResponseInterface` to have\nmore context to an error.\n\n## Credits\n\n- [Chris Döhring](https://github.com/chris-doehring)\n- [Philipp Marien](https://github.com/pmarien)\n- [eosnewmedia team](https://github.com/eosnewmedia)\n\nThis package contains code taken from [enm/json-api-client](https://github.com/eosnewmedia/JSON-API-Client).\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdogado-group%2Fjson-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdogado-group%2Fjson-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdogado-group%2Fjson-api-client/lists"}