art4/json-api-client

JSON API client

JsonApiClient

, _(*1)

JsonApiClient :construction_worker_woman: is a PHP Library to validate and handle the response body from a JSON API Server., _(*2)

Format: JSON API 1.0, _(*3)

:checkered_flag: Goals

• ✅ Be 100% JSON API 1.0 spec conform
• ⬜ Be open for new spec minor versions (see #90)
• ✅ Handle/validate a server response body
• ✅ Handle/validate a client request body
• ✅ Offer an easy way to retrieve the data
• ✅ Allow extendability and injection of classes/models

:package: Install

Via Composer, _(*4)

``` bash $ composer require art4/json-api-client, <sub>(*5)</sub>

### :building_construction: Upgrade to v1

**Version 1.0 is finally released.** :tada:

After version 0.8.0 there where no breaking changes. Every change was backward compatible and every functionality that was removed in v1.0 only triggers a deprecation warning in v0.10.

To upgrade from v0.x to v1 just update to 0.10.2 and resolve all deprecation warnings.

Or in 3 simple steps:

1. Update your composer.json to `"art4/json-api-client": "^0.10.2"`
2. Make your code deprecation warnings free
3. Upgrade your composer.json to `"art4/json-api-client": "^1.0"` without breaking your app

(Compare the [Symfony upgrade documentation](https://symfony.com/doc/current/setup/upgrade_major.html))

## :rocket: Usage

See the [quickstart guide](docs/helper-parser.md) or the [documentation](docs/README.md).

### Using as parser

```php
use Art4\JsonApiClient\Exception\InputException;
use Art4\JsonApiClient\Exception\ValidationException;
use Art4\JsonApiClient\Helper\Parser;

// The Response body from a JSON API server
$jsonapiString = '{"meta":{"info":"Testing the JsonApiClient library."}}';

try {
    // Use this if you have a response after calling a JSON API server
    $document = Parser::parseResponseString($jsonapiString);

    // Or use this if you have a request to your JSON API server
    $document = Parser::parseRequestString($jsonapiString);
} catch (InputException $e) {
    // $jsonapiString is not valid JSON
} catch (ValidationException $e) {
    // $jsonapiString is not valid JSON API
}

Note: Using Art4\JsonApiClient\Helper\Parser is just a shortcut for directly using the Manager., <sub>(*6)</sub>

$document implements the Art4\JsonApiClient\Accessable interface to access the parsed data. It has the methods has($key), get($key) and getKeys()., <sub>(*7)</sub>

// Note that has() and get() have support for dot-notated keys
if ($document->has('meta.info'))
{
    echo $document->get('meta.info'); // "Testing the JsonApiClient library."
}

// you can get all keys as an array
var_dump($document->getKeys());

// array(
//   0 => "meta"
// )

Using as validator

JsonApiClient can be used as a validator for JSON API contents:, <sub>(*8)</sub>

use Art4\JsonApiClient\Helper\Parser;

$wrong_jsonapi = '{"data":{},"meta":{"info":"This is wrong JSON API. `data` has to be `null` or containing at least `type` and `id`."}}';

if ( Parser::isValidResponseString($wrong_jsonapi) ) {
// or Parser::isValidRequestString($wrong_jsonapi)
    echo 'string is valid.';
} else {
    echo 'string is invalid json api!';
}

// echoes 'string is invalid json api!'

Extend the client

Need more functionality? Want to directly inject your model? Easily extend JsonApiClient with the Factory., <sub>(*9)</sub>

:loud_sound: Changelog

Please see CHANGELOG for more information what has changed recently., <sub>(*10)</sub>

:wrench: Contributing

Please feel free to fork and sending Pull Requests. This project follows Semantic Versioning 2 and PER-CS2.0., <sub>(*11)</sub>

This projects comes with a docker-compose.yml where all tools for development are available., <sub>(*12)</sub>

Run docker compose build to build the image. Once you've build it, run docker compose up -d to start the container in the background., <sub>(*13)</sub>

Run docker compose exec -u 1000 php bash to use the bash inside the running container. There you can use all tools, e.g. composer with composer --version, <sub>(*14)</sub>

Use exit to logout from the container and docker compose stop to stop the running container., <sub>(*15)</sub>

All following commands can be run inside the running docker container., <sub>(*16)</sub>

:white_check_mark: Testing

Run PHPUnit for all tests:, <sub>(*17)</sub>

``` bash $ composer run phpunit, <sub>(*18)</sub>

Run PHPStan for static code analysis:

``` bash
$ composer run phpstan

Let PHPUnit generate a HTLM code coverage report:, <sub>(*19)</sub>

``` bash $ composer run coverage, <sub>(*20)</sub>

You can find the code coverage report in `.phpunit.cache/code-coverage/index.html`.

### :white_check_mark: REUSE

The [REUSE Helper tool](https://reuse.software/dev/) makes licensing easy for humans and machines alike. It downloads the full license texts, adds copyright and license information to file headers, and contains a linter to identify problems.

Check all files for REUSE spec compliance:

``` bash
composer run reuse-lint

Run this command to annotate PHP files in src and tests folders:, <sub>(*21)</sub>

bash composer run reuse-annotate, <sub>(*22)</sub>

:heart: Credits

• Artur Weigandt
• All Contributors

:page_facing_up: License

GPL3. Please see License File for more information., <sub>(*23)</sub>