👷‍♀️ A PHP Library to handle the request or response body from a JSON API server.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

JsonApiClient

Latest Version Software License Build Status Coverage Status Total Downloads

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

Format: JSON API 1.0

Attention

Version 0.6.1 and below interprets the pagination links wrong. Make sure you are using the latest version of JsonApiClient. See #19, #23 and #26 for more information.

WIP: Goals for 1.0

  • Be 100% JSON API 1.0 spec conform
  • Handle/validate a server response body
  • Offer an easy way to retrieve the data
  • Be extendable and allow injection of classes/models
  • Handle/validate a client request body
  • Refactore and remove the deprecated code

Install

Via Composer

$ composer require art4/json-api-client

Usage

See the documentation.

Using as reader

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."}}';

// 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);

Using Art4\JsonApiClient\Helper\Parser::parseResponseString($jsonapiString) is a shortcut for directly using the Manager:

use Art4\JsonApiClient\Exception\InputException;
use Art4\JsonApiClient\Exception\ValidationException;
use Art4\JsonApiClient\Input\RequestStringInput;
use Art4\JsonApiClient\Input\ResponseStringInput;
use Art4\JsonApiClient\Manager\ErrorAbortManager;
use Art4\JsonApiClient\V1\Factory;

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

$manager = new ErrorAbortManager(
    new Factory()
);

// Use this if you have a response after calling a JSON API server
$input = new ResponseStringInput($jsonapiString);

// Or use this if you have a request to your JSON API server
$input = new RequestStringInput($jsonapiString);

try {
    $document = $manager->parse($input);
} catch (InputException $e) {
    // $jsonapiString is not valid JSON
} catch (ValidationException $e) {
    // $jsonapiString is not valid JSON API
}

// do something with $document

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

// 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 use Parser::isValidRequestString($wrong_jsonapi)
	echo 'string is valid.';
} else {
	echo 'string is invalid json api!';
}

// echos '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

License

GPL3. Please see License File for more information.