mattjanssen/api-response-bundle
![Software License][ico-license]
, (*1)
mattjanssen/api-response-bundle is a slightly-opinionated Symfony bundle for transforming controller action returns
and exceptions into a standardized JSON response. The serializer and CORS headers can be configured globally, per path,
and per action via annotation., (*2)
Install
Via Composer, (*3)
``` bash
$ composer require mattjanssen/api-response-bundle, (*4)
## Enable
Enable the bundle in the kernel:
``` php
<?php
// app/AppKernel.php
public function registerBundles()
{
$bundles = [
// ...
new MattJanssen\ApiResponseBundle\ApiResponseBundle(),
];
}
``` yml
api_response:
defaults:
serializer: json_encode
serialize_groups: []
cors_allow_origin_regex: https://..mydomain.com
cors_allow_headers: [Authorization, Content-Type]
cors_max_age: 86400
paths:
somename:
prefix: /api/v1/
serializer: jms_serializer
othername:
pattern: ^/api/v[2-4]/
cors_allow_origin_regex: ., (*5)
The serializer can be empty, 'array', 'json_encode', 'json_group_encode', 'jms_serializer',
or the name of a service which must implement the SerializerAdapterInterface. It defaults to 'json_encode'.
## Usage
In your API controllers, just return whatever you want serialized in the response. The ApiResponseBundle takes care of
turning that into an actual JSON response.
``` php
return [
'id' => 5,
'school' => $school,
'users' => $users,
];
This would result in the following JSON return:, (*6)
``` javascript
{
data: {
id: 5,
school: ...,
users: [ ... ]
},
error: null
}, (*7)
## Status Codes
By default, responses are sent with the 200 OK status. In order to use a different status, use the `@ApiResponse`
annotation on the controller action. This should only be used to change the success status codes. See the Error Response
section for handling error output.
``` php
/**
* @ApiResponse(httpCode=201)
*/
public function createAction() {}
The resulting response would have the 201 CREATED status., (*8)
Error Response
To respond with an error, throw any exception implementing the ApiResponseExceptionInterface. On the exception you can
optionally set the HTTP status code, the exception code, the exception message and the error data to be serialized into the
response., (*9)
``` php
throw (new ApiResponseException())
->setHttpStatusCode(404)
->setCode(100404)
->setMessage('Could not find school.')
->setErrorData(['schoolId' => 42]);, (*10)
This would result in the following JSON return with a 404 HTTP status:
``` javascript
{
data: null,
error: {
code: 100404,
message: 'Could not find school.',
errorData: {
schoolId: 42
}
}
}
Exception Handling
Besides turning ApiResponseExceptionInterface exceptions into error responses, the bundle will also handle any
uncaught exceptions in the following manner:, (*11)
HttpExceptionInterface
The exception status code is used for both the response HTTP code and the error code. The error message is the
corresponding Response::$statusTexts array value. Error data is null., (*12)
AuthenticationException
Both the response HTTP code and the error code are 401. The error message is "Unauthorized". Error data is null., (*13)
AccessDeniedException
Both the response HTTP code and the error code are 403. The error message is "Forbidden". Error data is null., (*14)
All Other Exceptions
Both the response HTTP code and the error code are 500., (*15)
If the Symfony kernel is not in debug mode, the error message is "Internal Server Error". Error data is null., (*16)
If the Symfony kernel is in debug mode, the error message is compiled from the exception class, message, file and
line number. And the error data is the exception trace., (*17)
Testing
bash
$ composer install --dev
$ vendor/bin/phpunit, (*18)
License
The MIT License (MIT). Please see License File for more information., (*19)
Wallogit.com
