JsonApi Response factory

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"
      }
    }
  ]
}