README

👁 Latest Version
👁 Software License
👁 Total Downloads

A small wrapper around league/fractal to support JsonApi error AND success responses.

Install

composer require happyr/json-api-response-factory

Usage

ResponseFactory can be used for creating single object, collection of objects or custom responses.

Transformers

Each object that is used in the response needs a transformer that implements Happyr\JsonApiResponseFactory\Transformer\AbstractTransformer:

use Happyr\JsonApiResponseFactory\Transformer\AbstractTransformer;

final class FooTransformer extends AbstractTransformer
{
 public function getResourceName(): string
 {
 return 'foo';
 }

 public function transform(Foo $item): array
 {
 return [
 'id' => $item->getId(),
 'bar' => (string)$item->getBar(),
 ];
 }
}

Response with single item

$item = new Foo('bar');
$response = $responseFactory->createWithItem($item, new FooTransformer());

Response will look like this:

{
 "data": {
 "type": "foo",
 "id": "1",
 "attributes": {
 "bar": "bar"
 }
 }
}

Response with collection of items

$items = [
 new Foo('bar'),
 new Foo('baz'),
];
$response = $responseFactory->createWithCollection($items, new FooTransformer());

Response will look like this:

{
 "data": [
 {
 "type": "foo",
 "id": "1",
 "attributes": {
 "bar": "bar"
 }
 },
 {
 "type": "foo",
 "id": "2",
 "attributes": {
 "bar": "baz"
 }
 }
 ]
}

Custom responses

To use response ResponseFactory to create response with custom payload/status codes you should create class that implements Happyr\JsonApiResponseFactory\ResponseModelInterface:

use Happyr\JsonApiResponseFactory\ResponseModelInterface;

final class InvalidRequestResponseModel implements ResponseModelInterface
{
 public function getHttpStatusCode() : int
 {
 return 400;
 }

 public function getPayload() : array
 {
 return [
 'error' => 'Invalid request.',
 ];
 }
}

and pass it to response factory:

$model = new InvalidRequestResponseModel();
$response = $responseFactory->createWithResponseModel($model);

Response will look lie this:

{
 "error": "Invalid request."
}

In src/Model/ there are models for usual message responses (accepted, created etc), and error responses in compliance with json-api error standard that you can use, or take a hint how we are using the library and write your own models.

Example response for message:

{
 "meta": {
 "message": "Accepted"
 }
}

Example response for validation failed:

{
 "errors": [
 {
 "status": "400",
 "title": "Validation failed",
 "detail": "This value should not be blank.",
 "source": {
 "parameter": "foo",
 },
 "links": {
 "about": "http://docs.docs/errors/missing-parameter"
 }
 },
 {
 "status": "400",
 "title": "Validation failed",
 "detail": "This value has to be larger than 30.",
 "source": {
 "parameter": "bar",
 },
 "links": {
 "about": "http://docs.docs/errors/range"
 }
 }
 ]
}