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 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:
- 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.
π§ 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
π License
GPL3. Please see License File for more information.