Simple package to handle response properly in your API. This package use Fractal and are based on Build APIs You Won't Hate book.
Via Composer
$ composer require ellipsesynergie/api-responseThe following versions of PHP are supported by this version.
- PHP 5.4
- PHP 5.5
- PHP 5.6
- PHP 7.0-dev
- HHVM
Unfortunately, since the release 0.9.0, Laravel 4 is no longer supported because league/fractal@0.12 no longer support this version.
Once this operation completes, you need to add the service provider. Open app/config/app.php, and add a new item to the providers array.
EllipseSynergie\ApiResponse\Laravel\ResponseServiceProviderOnce this operation completes, you need to add the service provider. Open bootstrap/app.php, and register this provider.
$app->register('EllipseSynergie\ApiResponse\Laravel\LumenServiceProvider');You also need to uncomment the line $app->withFacades(); in the file bootstrap/app.php
This package can be used in ANY framework or vanilla php. You simply need to extend EllipseSynergie\ApiResponse\AbstractResponse and implement the withArray() method in your custom class.
You can take a look at EllipseSynergie\ApiResponse\Laravel\Response::withArray() for a example.
If you have created a new implementation for a specific framework, i strongly recommend you to send a pull request to this repository.
You will also need to instantiate the response class with a fractal manager instance.
// Instantiate the fractal manager
$manager = new \League\Fractal\Manager;
// Set the request scope if you need embed data
$manager->parseIncludes(explode(',', $_GET['include']));
// Instantiate the response object, replace the class name by your custom class
$response = new \EllipseSynergie\ApiResponse\AbstractResponse($manager);For more option related to fractal manager, you can take a look at the official website
<?php
use EllipseSynergie\ApiResponse\Contracts\Response;
class BookController extends Controller {
/**
* @param Response
*/
public function __construct(Response $response)
{
$this->response = $response;
}
/**
* Example returning collection
*/
public function index()
{
//Get all books
$books = Book::all();
// Return a collection of $books
return $this->response->withCollection($books, new BookTransformer);
}
/**
* Example returning collection with custom key
*/
public function index()
{
//Get all books
$books = Book::all();
//Custom key
$customKey = 'books';
// Return a collection of books
return $this->response->withCollection($books, new BookTransformer, $customKey);
}
/**
* Example returning collection with paginator
*/
public function index()
{
//Get all books
$books = Book::paginate(15);
// Return a collection of $books with pagination
return $this->response->withPaginator(
$books,
new BookTransformer
);
}
/**
* Example returning collection with paginator with custom key and meta
*/
public function index()
{
//Get all books
$books = Book::paginate(15);
//Custom key
$customKey = 'books';
//Custom meta
$meta = [
'category' = 'fantasy'
];
// Return a collection of $books with pagination
return $this->response->withPaginator(
$books,
new BookTransformer,
$customKey,
$meta
);
}
/**
* Example returning item
*/
public function show($id)
{
//Get the book
$book = Book::find($id);
// Return a single book
return $this->response->withItem($book, new BookTransformer);
}
/**
* Example returning item with a custom key and meta
*/
public function showWithCustomKeyAndMeta($id)
{
//Get the book
$book = Book::find($id);
//Custom key
$customKey = 'book';
//Custom meta
$meta = [
'readers' = $book->readers
];
// Return a single book
return $this->response->withItem($book, new BookTransformer, $customKey, $meta);
}
/**
* Example resource not found
*/
public function delete($id)
{
//Try to get the book
$book = Book::find($id);
//Book not found sorry !
if(!$book){
return $this->response->errorNotFound('Book Not Found');
}
}
/**
* Example method not implemented
*/
public function whatAreYouTryingToDo()
{
return $this->response->errorMethodNotAllowed("Please don't try this again !");
}
}##Ouput example
###One book
{
"data": {
"id": 1,
"title": "My name is Bob!.",
"created_at": {
"date": "2014-03-25 18:54:18",
"timezone_type": 3,
"timezone": "UTC"
},
"updated_at": {
"date": "2014-03-25 18:54:18",
"timezone_type": 3,
"timezone": "UTC"
},
"deleted_at": null
}
}###Collection of books
{
"data": [
{
"id": 1,
"title": "My name is Bob!",
"created_at": {
"date": "2014-03-25 18:54:18",
"timezone_type": 3,
"timezone": "UTC"
},
"updated_at": {
"date": "2014-03-25 18:54:18",
"timezone_type": 3,
"timezone": "UTC"
},
"deleted_at": null
},
{
"id": 2,
"title": "Who's your dady ?",
"created_at": {
"date": "2014-03-26 18:54:18",
"timezone_type": 3,
"timezone": "UTC"
},
"updated_at": {
"date": "2014-03-26 18:54:18",
"timezone_type": 3,
"timezone": "UTC"
},
"deleted_at": null
}
]
}###Error
{
"error": {
"code": "GEN-NOT-FOUND",
"http_code": 404,
"message": "Book Not Found"
}
}$ phpunitThe MIT License (MIT). Please see License File for more information.