art4 / json-api-client
JSON API client
Installs: 662 330
Dependents: 9
Suggesters: 0
Security: 0
Stars: 138
Watchers: 13
Forks: 20
Open Issues: 6
Requires
- php: ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.64
- phpstan/phpstan: ^1.10
- phpstan/phpstan-phpunit: ^1.3
- phpunit/phpunit: ^10.4
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:
- 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.