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.