tequilarapido / api-response
A simple way to return well formatted json responses in a Laravel application.
Installs: 12 822
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 4
Forks: 0
Open Issues: 8
Requires
- php: ^7.1.3
- laravel/framework: ~5.8.0|^6.0|^7.0
- league/fractal: ^0.14.0
Requires (Dev)
- orchestra/testbench: ^3.8
- dev-master
- v1.1.6
- v1.1.5
- v1.1.4
- v1.1.3
- 1.1.0
- 1.0.x-dev
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- 0.0.2
- 0.0.1
- dev-dependabot/npm_and_yarn/path-parse-1.0.7
- dev-dependabot/npm_and_yarn/hosted-git-info-2.8.9
- dev-dependabot/npm_and_yarn/lodash-4.17.21
- dev-dependabot/npm_and_yarn/handlebars-4.7.7
- dev-dependabot/npm_and_yarn/y18n-3.2.2
- dev-dependabot/npm_and_yarn/ini-1.3.7
- dev-dependabot/npm_and_yarn/standard-version-8.0.1
- dev-dependabot/npm_and_yarn/lodash.template-4.5.0
- dev-develop
This package is auto-updated.
Last update: 2024-10-11 05:04:44 UTC
README
A simple way to return well formatted json responses in a Laravel application.
Installation
You can install the package using composer
$ composer require tequilarapido/api-response
Add the service provider
Tequilarapido\ApiResponse\ApiResponseServiceProvider::class
Usage
This package comes with a helper function api_response()
, as sugar syntax to using app(Tequilarapido\ApiResponse\ApiResponse::class)
Return a response from an item (Array / Associative array / Object/)
return api_response()->item(['result`' => 'success'])
Result :
{
"data":
{
"result":
"success"
}
}
Return a response from a collection
return api_response()->item(collect(['Apple', 'Orange', 'Kiwi']))
Result :
{
"data":
{
"Apple",
"Orange",
"Kiwi",
}
}
Return a response from a paginated collection
return api_response()->item(collect(['Apple', 'Orange', 'Kiwi']))
Result :
{
"data": [1, 2, 3],
"meta": {
"pagination": {
"count": 3,
"current_page": 1,
"links": {
"next": "/?page=2"
},
"per_page": 3,
"total": 15,
"total_pages": 5
}
}
}
Transformers
You can use transformers along with item()
, collection()
, and paginatedCollection
methods to transform results
before returning the responses.
To learn more about the concept behind transformers, please read the League\Fractal documentation.
Put in a simple way, a Transformer class
- must extends League\Fractal\TransformerAbstract
- and contains a method transform()
that take the raw value/object as an argument and transform it the way we want.
Let's assume that we need to return an api response containing a collection of books retreived from database, and we want to format/enhance/restrict results.
class BookTransformer extends TransformerAbstract { public function transform($book) { return [ 'id' => (int)$book->id, 'title' => strtoupper($book->title), 'price' => '$' . $book->price, 'published_at' => $book->published_at->format('d/m/Y'), 'url' => 'https://store.books.com/books/' . $book->id ]; } }
Route::get('/books', function () { // ie. Book::all() $books = collect([ (object)['title' => 'An awesome book', 'id' => '1', 'price' => 10, 'published_at' => Carbon::createFromFormat('Y-m-d', '2016-10-01')], (object)['title' => 'A second awesome book', 'id' => '2', 'price' => 100, 'published_at' => Carbon::createFromFormat('Y-m-d', '2016-10-02')], ]); return api_response()->collection($books, new BookTransformer); });
Result:
{
"data": [
{
"id": 1,
"price": "$10",
"published_at": "01/10/2016",
"title": "AN AWESOME BOOK",
"url": "https://store.books.com/books/1"
},
{
"id": 2,
"price": "$100",
"published_at": "02/10/2016",
"title": "A SECOND AWESOME BOOK",
"url": "https://store.books.com/books/2"
}
]
}
Attaching cookies
For item()
, collection()
, and paginatedCollection
methods the returned result is a built Illuminate\Http\Response
object.
To be able to attach cookies you need to instruct api_response()
methods to not build the response by setting the $built argument to false, attach the cookie
and then build the response.
return api_response() ->item(['result`' => 'success'], null, null, false) ->withCookie(new \Symfony\Component\HttpFoundation\Cookie('name', 'value')) ->build();
Attaching headers
For item()
, collection()
, and paginatedCollection
methods the returned result is a built Illuminate\Http\Response
object.
To be able to attach headers you need to instruct api_response()
methods to not build the response by setting the $built argument to false, attach the header
and then build the response.
return api_response() ->item(['result`' => 'success'], null, null, false) ->withHeader('X-CUSTOM', 'customvalue') ->build();
Other useful methods
Changelog
Please see CHANGELOG for more information what has changed recently.
Testing
$ composer test
Security
If you discover any security related issues, please email :author_email instead of using the issue tracker.
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.