shkm / jsend
A simple PHP implementation of the JSend specification.
Requires
- php: >=7.4
- ext-json: *
Requires (Dev)
- ext-xdebug: *
- phpunit/phpunit: ^9
README
JSend
A simple PHP implementation of the JSend specification.
Usage
use JSend\JSendResponse;
New response
$success = new JSendResponse('success', $data); $fail = new JSendResponse('fail', $data); $error = new JSendResponse('error', $data, 'Not cool.', 9001);
$success = JSendResponse::success($data); $fail = JSendResponse::fail($data); $error = JSendResponse::error('Not cool.', 9001, $data);
Note: an InvalidJSendException
is thrown if the status is invalid or if you're creating an error
without a message
.
Convert JSendResponse to JSON
__toString()
is overridden to encode JSON automatically.
$json = $success->encode(); $json = (string) $success;
As JSendResponse is JsonSerializable
, you can use the object directly in json_encode
json_encode($success);
Setting flags
You can set flags if needed:
$success->setEncodingOptions(\JSON_PRETTY_PRINT | \JSON_BIGINT_AS_STRING); $json = $success->encode();
Convert JSON to JSendResponse
try { $response = JSendResponse::decode($json); } catch (InvalidJSendException $e) { echo "You done gone passed me invalid JSend."; }
Send JSON as HTTP Response
This sets the Content-Type
header to application/json
and spits out the JSON.
$jsend = new JSendResponse('success', $data); $jsend->respond();
Get info
$isSuccess = $response->isSuccess(); $isError = $response->isError(); $isFail = $response->isFail(); $status = $response->getStatus(); $data = $response->getData(); $array = $response->asArray();
Additionally, you can call the following methods on an error. A BadMethodCallException
is thrown if the status is not error
, so check first.
if ($response->isError()) { $code = $response->getErrorCode; $message = $response->getErrorMessage; }
Development
For your convenience, there is a dockerfile with the right dependencies (php, composer) available. Please use those
to run various things (composer, phpunit, etc). You will need docker
and docker-compose
installed, but you don't
need PHP
or composer
.
Setting up your install
Running ./install.sh
will run composer for you in a development container. It does some magic with a .user.env
file that will make sure you run all the stuff as your local user. This will help with access to the generated files.
You can run ./bin/composer
if you want to do any composer
things, like composer update
. If that takes to long each
time, you can jump in a shell by using ./bin/shell
. This makes sure you always run your build (or test) commands in
the right environment.
Testing and code quality
There are scripts in /bin
to help you test for issues:
- codeclimate: run various codeclimate checks, like phpcodesniffer, phan, etc. See
.codeclimate.yml
- phpunit: runs the testsuite
These tests are run on the CI as well, but please make sure they don't fail before you do a PR
Notes
- Note that the
composer.lock
file is ignored. This is standard practice for libraries. - The current tests are done on php 7.2, but tests are for 7.3 and 7.4 as well
Credits
The library was written by Jamie Schembri. It has been transfered to the current account Nanne Huiges in december 2015.