happyr / json-api-response-factory
Response factory in compliance with apijson
Fund package maintenance!
Nyholm
Installs: 59 741
Dependents: 0
Suggesters: 0
Security: 0
Stars: 9
Watchers: 2
Forks: 3
Open Issues: 0
Requires
- php: >=7.4
- ext-json: *
- league/fractal: ^0.18 || ^0.19 || ^0.20
- symfony/http-foundation: ^5.4 || ^6.0
- symfony/validator: ^5.4 || ^6.0
Requires (Dev)
- nyholm/nsa: ^1.1
- phpunit/phpunit: ^9.5
This package is auto-updated.
Last update: 2024-10-28 05:42:25 UTC
README
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" } } ] }