carpediem/jsend

An Immutable Value Object JSend compliant

JSend

, _(*1)

JSend is a simple library to ease the use of JSend compliant objects., _(*2)

<?php

use Carpediem\JSend\JSend;

$data = [
    'post' => [
        'id' => 1,
        'title' => 'foo',
        'author' => 'bar',
    ],
];
$response = JSend::success($data);
$response->send(['Access-Control-Allow-Origin' => 'example.com']);
die;

Highlights

• Simple API
• Immutable Value Object

System Requirements

You need PHP >= 7.0 to use JSend but the latest stable version of PHP/HHVM is recommended., _(*3)

Install

Install JSend using Composer., _(*4)

$ composer require carpediem/jsend

Documentation

Class summary

final class JSend implements JsonSerializable
{
    const STATUS_SUCCESS = 'success';
    const STATUS_ERROR = 'error';
    const STATUS_FAIL = 'fail';

    public static function fromJSON($json, int $depth = 512, int $options = 0): self;
    public static function fromArray(array $arr): self;
    public static function success($data = null): self;
    public static function fail($data = null): self;
    public static function error($errorMessage, int $errorCode = null, $data = null): self;
    public function getStatus(): string;
    public function getData(): array;
    public function getErrorMessage(): ?string;
    public function getErrorCode(): ?int;
    public function isSuccess(): bool;
    public function isFail(): bool;
    public function isError(): bool;
    public function toArray(): array;
    public function __toString(): string;
    public function jsonSerialize(): array;
    public function send(array $headers = []): int;
    public function withStatus(string $status): self;
    public function withData($data): self;
    public function withError($errorMessage, int $errorCode = null): self;
}

Class Import

<?php

use Carpediem\JSend\JSend;

Create new instances

Use named constructors to instantiate a JSend object creation, _(*5)

$success = JSend::success($data);
$fail = JSend::fail($data);
$error = JSend::error('Not Found', 404, $data);
$response = JSend::fromJSON('{"status":"success","data":{"post":{"id":1,"title":"foo","author":"bar"}}}');
$altResponse = JSend::fromArray(['data' => ['post' => 1], 'code' => 404, 'message' => 'Post not Found']);

If the object can not be created a Carpediem\JSend\Exception will be thrown., _(*6)

Access properties

$response = JSend::error('Not Found', 404, ['post' => 1234]);
$response->getStatus();       // returns 'success, 'error', 'fail'
$response->getErrorMessage(); // returns 'Not Found'
$response->getErrorCode();    // returns 404
$response->getData();         // returns $data
$response->isSuccess();       // boolean
$response->isFail();          // boolean
$response->isError();         // boolean

• JSend::getErrorMessage returns null when JSend::getStatus is not equal to error;
• JSend::getErrorCode is an integer or null;

Manipulations

$response = JSend::success(['post' => 1234]);
(string) $response;  // returns {"status": "success", "data": {"post": 1234}}
echo json_encode($response, JSON_PRETTY_PRINT);
// returns
// {
//    "status": "success",
//    "data": {
//        "post": 1234
//    }
//}
$response->toArray();
// returns
// [
//    'status' => 'success',
//    'data' => [
//        'post' => 1234,
//    ]
// ]

Updates

The JSend object is immutable so any changes to the object will return a new object, _(*7)

$response = JSend::success();
$newResponse = $response->withData(['post' => 1234]);
$failResponse = $response->witStatus(JSend::STATUS_FAIL);
$errorResponse = $response->withError('This is an error', 404);

echo $response;      // returns {"status": "success"}
echo $newResponse;   // returns {"status": "success", "data": {"post": 1234}}
echo $failResponse;  // returns {"status": "fail"}
echo $errorResponse; // returns {"status": "error", "message": "This is an error", code: 404}

JSend::withData accepts the null value, an array or a JsonSerializable objects whose jsonSerialize method returns an array, _(*8)

JSend::withError $errorCode parameter is optional, _(*9)

Creating an HTTP Response

header('HTTP/1.1 404 Not Found'); // don't forget to add the HTTP header
$response = JSend::fail(['post' => 1234]);
$response->send(['Access-Control-Allow-Origin' => '*']);
die;

JSend::send accepts additional headers in form of key/value pairs., _(*10)

Testing

the library has a:, _(*11)

• a PHPUnit test suite
• a coding style compliance test suite using PHP CS Fixer.
• a code analysis compliance test suite using PHPStan.

To run the tests, run the following command from the project folder., _(*12)

bash $ composer test, _(*13)

Contributing

Contributions are welcome and will be fully credited. Please see CONTRIBUTING for details., _(*14)

Security

If you discover any security related issues, please email dev@carpediem.fr instead of using the issue tracker., _(*15)

Credits

• All Contributors

License

The MIT License (MIT). Please see LICENSE for more information., _(*16)