mdance/json-api-client

:construction_worker_woman: A PHP Library to handle the request or response body from a JSON API server.

JsonApiClient

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 spec conform
• ✔️ Be open for new spec versions
• ✔️ 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.

✅ Testing

$ phpunit

🔧 Contributing

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

❤️ Credits

• Artur Weigandt
• All Contributors

📄 License

GPL3. Please see License File for more information.