JsonApiClient
JsonApiClient
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:
- Update your composer.json to
"art4/json-api-client": "^0.10.2"
- Make your code deprecation warnings free
- 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
๐ License
GPL3. Please see License File for more information.