Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/carpediem/jsend
A PHP Immutable Value Object implementing the JSend specification
https://github.com/carpediem/jsend
Last synced: 12 days ago
JSON representation
A PHP Immutable Value Object implementing the JSend specification
- Host: GitHub
- URL: https://github.com/carpediem/jsend
- Owner: carpediem
- License: mit
- Created: 2015-11-20T13:27:40.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2018-09-07T13:58:29.000Z (over 6 years ago)
- Last Synced: 2024-12-12T18:51:52.331Z (13 days ago)
- Language: PHP
- Homepage: https://github.com/carpediem/JSend
- Size: 92.8 KB
- Stars: 6
- Watchers: 5
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
JSend
==========
[](https://github.com/carpediem/jsend/releases)
[](LICENSE.md)
[](https://travis-ci.org/carpediem/JSend)
[](https://scrutinizer-ci.com/g/carpediem/jsend/code-structure)
[](https://scrutinizer-ci.com/g/carpediem/jsend)
[](https://packagist.org/packages/carpediem/jsend)
JSend is a simple library to ease the use of [JSend compliant](https://labs.omniti.com/labs/jsend) objects.
```php
[
'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.
Install
-------
Install `JSend` using Composer.
```
$ composer require carpediem/jsend
```
Documentation
-------
### Class summary
```php
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
['post' => 1], 'code' => 404, 'message' => 'Post not Found']);
```
If the object can not be created a `Carpediem\JSend\Exception` will be thrown.
### Access properties
```php
$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
```php
$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
```php
$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`**
**`JSend::withError` `$errorCode` parameter is optional**
### Creating an HTTP Response
```php
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.
Testing
-------
the library has a:
- a [PHPUnit](https://phpunit.de) test suite
- a coding style compliance test suite using [PHP CS Fixer](http://cs.sensiolabs.org/).
- a code analysis compliance test suite using [PHPStan](https://github.com/phpstan/phpstan).
To run the tests, run the following command from the project folder.
``` bash
$ composer test
```
Contributing
-------
Contributions are welcome and will be fully credited. Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
Security
-------
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Credits
-------
- [All Contributors](https://github.com/carpediem/JSend/graphs/contributors)
License
-------
The MIT License (MIT). Please see [LICENSE](LICENSE) for more information.
[PSR-2]: http://www.php-fig.org/psr/psr-2/
[PSR-4]: http://www.php-fig.org/psr/psr-4/