README

JsonApiClient ????‍♀️ is a PHP Library to validate and handle the response body from a JSON API Server.

Format: JSON API 1.0

???? 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

???? Install

Via Composer

$ composer require art4/json-api-client

????️ Upgrade to v1

Version 1.0 is finally released. ????

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)

???? Usage

See the quickstart guide or the documentation.

Using as parser

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.

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

// 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:

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.

???? Changelog

Please see CHANGELOG for more information what has changed recently.

???? Contributing

Please feel free to fork and sending Pull Requests. This project follows Semantic Versioning 2 and PER-CS2.0.

This projects comes with a docker-compose.yml where all tools for development are available.

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.

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

Use exit to logout from the container and docker compose stop to stop the running container.

All following commands can be run inside the running docker container.

✅ Testing

Run PHPUnit for all tests:

$ composer run phpunit

Run PHPStan for static code analysis:

$ composer run phpstan

Let PHPUnit generate a HTLM code coverage report:

$ composer run coverage

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

✅ REUSE

The REUSE Helper tool 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:

composer run reuse-lint

Run this command to annotate PHP files in src and tests folders:

composer run reuse-annotate

❤️ Credits

• Artur Weigandt
• All Contributors

???? License

GPL3. Please see License File for more information.