gridonic/json-response

Structures JSON responses for the JSend format

1.1.1 2015-02-20 13:57 UTC

README

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.

Build Status

Install

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';

JsonResponse

We differentiate between two different types of Responses:

  • SuccessJsonResponse
  • ErrorJsonResponse

SuccessJsonResponse

/**
 * @throws \InvalidArgumentException
 */
 new SuccessJsonResponse($data, 'Success message', 'Success title', 200);
{
    "status" : "success",
    "data" : { ... },
    "message" : "Sucess message",
    "title" : "Success title"
}

ErrorJsonResponse

/**
 * @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" : { ... }
}

JSend

Our Responses are based on the Model of JSend. You can find the documentation of JSend on the JSend website

Usage

SuccessJsonResponse

Use a Gridonic\JsonResponse\SuccessJsonResponse to build a structured JSON Response.

Empty SuccessJsonResponse

new SuccessJsonResponse();
{
    "status" : "success",
    "data" : null
}

SuccessJsonResponse with Content

$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!"
}

SuccessJsonResponse

Use a Gridonic\JsonResponse\ErrorJsonResponse to build a structured JSON Response.

ErrorJsonResponse with Message

$message = 'Oups, data is missing.';

new ErrorJsonResponse(null, $message); // you have to send a message!
{
    "status" : "error",
    "data" : null,
    "message" : "Oups, data is missing"
}

ErrorJsonResponse with Content

$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

1.1.0

New structure of the responses

1.0.0

Initial Release

Licence

The JsonResponse is licensed under the MIT license.