Provides simple classes for JSON responses that adhere to a standardized structure. Since JSON responses may have very different formats, this package supports the specific JSend format defined at http://labs.omniti.com/labs/jsend.
This package is an extension of the HttpFoundation\JsonResponse class from the Symfony package.
The recommended way to install JsonResponse is through composer.
You can either add it as a depedency to your project using the command line:
$ composer require gridonic/json-response
or by adding it directly to your composer.json
file:
{
"require": {
"gridonic/json-response": "1.*"
}
}
Run these two commands to install it:
$ curl -s http://getcomposer.org/installer | php
$ php composer.phar install
Now you can add the autoloader, and you will have access to the library:
<?php
require 'vendor/autoload.php';
We differentiate between two different types of Responses:
- SuccessJsonResponse
- ErrorJsonResponse
Parameter | Type | Needed? | Default value | Description |
---|---|---|---|---|
$data |
mixed | optional | null | The response data |
$message |
string | optional | null | A success message |
$title |
string | optional | null | A success title |
$status |
integer | optional | 200 | The response status code |
$headers |
array | optional | array() | An array of response headers |
/**
* @throws \InvalidArgumentException
*/
new SuccessJsonResponse($data, 'Success message', 'Success title', 200);
{
"status" : "success",
"data" : { ... },
"message" : "Sucess message",
"title" : "Success title"
}
Parameter | Type | Needed? | Default value | Description |
---|---|---|---|---|
$data |
mixed | optional | null | The response data |
$message |
string | required | The error message | |
$title |
string | optional | null | An error title |
$status |
integer | optional | 400 | The response status code |
$errorCode |
string | optional | null | An individual error code |
$errors |
array | optional | array() | An array of errors |
$headers |
array | optional | array() | An array of response headers |
/**
* @throws \InvalidArgumentException
*/
new ErrorJsonResponse($data, 'Error message', 'Error title', 400, 'e311', $errors);
{
"status" : "error",
"data" : { ... },
"message" : "Error message",
"title" : "Error title",
"error_code" : "e311",
"errors" : { ... }
}
Our Responses are based on the Model of JSend. You can find the documentation of JSend on the JSend website
Use a Gridonic\JsonResponse\SuccessJsonResponse
to build a structured JSON Response.
new SuccessJsonResponse();
{
"status" : "success",
"data" : null
}
$data = array(
'post' => array(
'id' => 1,
'title' => 'A blog post',
)
);
$message = 'The Blog post was successfully created.';
$title = 'Successfully created!';
$statusCode = 205;
new SuccessJsonResponse($data, $message, $title, $statusCode);
{
"status" : "success",
"data" : {
"post": {
"id" : 1,
"title" : "A blog post"
}
},
"message" : "The Blog post was successfully created.",
"title" : "Successfully created!"
}
Use a Gridonic\JsonResponse\ErrorJsonResponse
to build a structured JSON Response.
$message = 'Oups, data is missing.';
new ErrorJsonResponse(null, $message); // you have to send a message!
{
"status" : "error",
"data" : null,
"message" : "Oups, data is missing"
}
$data = array(
'post' => array(
'title' => 'A blog post',
)
);
$message = 'Oups, data is not correct.';
$title = 'An error occured!';
$statusCode = 400;
$errorCode = e311;
$errors = array(
'body' => 'The parameter is missing.',
'title' => 'This parameter is too long.'
);
new ErrorJsonResponse($data, $message, $title, $statusCode, $errorCode, $errors);
{
"status" : "error",
"data" : {
"post": {
"title" : "A blog post"
}
},
"message" : "Oups, data is missing",
"title" : "An error occured",
"error_code" : "e311",
"errors" : {
"body" : "The parameter is missing.",
"title" : "This parameter is too long."
}
}
Major & Minor Releases
New structure of the responses
Initial Release
The JsonResponse is licensed under the MIT license.