mdhesari / api-response
Simple Laravel package to return Json responses.
Fund package maintenance!
Ko Fi
Requires
- php: ^7.3|^8.0|^8.1
- andreaselia/laravel-api-to-postman: ^1.15
Requires (Dev)
- orchestra/testbench: ^6.0
- phpunit/phpunit: ^9.5
- dev-mdhesari-master
- 2.0.0
- 1.0.1
- 1.0.0
- 0.16.0
- v0.15.0
- v0.14.0
- v0.13.0
- v0.12.1
- v0.12.0
- v0.11.0
- v0.10.2
- v0.10.1
- v0.10.0
- v0.9.7
- v0.9.5
- v0.9.1
- v0.9.0
- 0.4.0
- v0.3.0
- v0.2.53
- v0.2.51
- v0.2.7
- v0.2.6
- v0.2.5
- v0.2.0
- v0.1.5
- v0.1.1
- v0.1.0
- dev-mdhesari
- dev-move-messages-to-translation-files
- dev-master
- dev-Status-Improvements
- dev-analysis-OMbpmP
- dev-analysis-642PWW
- dev-Refactor-Code
- dev-analysis-wjND6W
- dev-analysis-Vrnmm6
- dev-analysis-1bw35P
- dev-docs
This package is auto-updated.
Last update: 2024-10-17 18:08:39 UTC
README
Simple Laravel API response wrapper.
Installation
-
Install the package through composer:
$ composer require mdhesari/api-response
-
Register the package service provider to the providers array in
app.php
file:Obiefy\API\ApiResponseServiceProvider::class
-
Register the package facade alias to the aliases array in
app.php
file:'API' => Obiefy\API\Facades\API::class,
-
And finally you can publish the config file:
php artisan vendor:publish --tag=api-response
Note: You could also include "use Obiefy\API\Facades\API;
" at the top of the class, but we recommend not to.
Basic usage
There are to ways of utilizing the package: using the facade
, or using the helper
function.
On either way you will get the same result, it is totally up to you.
Facade:
use API; ... public function index() { $users = User::all(); return API::response(200, 'users list', $users); }
Note: If you decide not to register the service provider and the facade, alias then you need to include use Obiefy\API\Facades\API;
at the top of the class, but we recommend not to.
Helper function:
public function index() { $users = User::all(); return api()->response(200, 'users list', $users); }
Advanced usage
The response()
method accepts three mandatory parameters:
int $status
string $message
string | array $data
For example, in the below example we are calling the response()
method thru the facade and we are passing the following parameters: 200
as the status code, User list
as the message and $users
(a collection of users) as the data.
use API; ... public function index() { $users = User::all(); return API::response(200, 'Users list', $users); }
This is the result:
{ "STATUS": 200, "MESSAGE": "Users list", "DATA": [ {"name": "Obay Hamed"} ] }
If you need more data other than the defaults STATUS
, MESSAGE
, and DATA
attributes on your json response, you could pass as many parameters as you need after $data
. However, we do recommend formating the extra parameters as a $key => $value
array.
As you can see in the below example, we are calling the api()
helper and we are passing the following parameters: 200
as the status code, User list
as the message, $users
(a collection of users) as the data, $code
as a key value array and $error
as another key value array.
public function index() { $users = User::all(); $code = ['code' => 30566]; $error = ['reference' => 'ERROR-2019-09-14']; return api()->response(200, 'Users list', $users, $code, $error); }
This is the result:
{ "STATUS": 200, "MESSAGE": "Users list", "DATA": [ {"name": "Obay Hamed"} ], "code": 30566, "error": "ERROR-2019-09-14" }
Another way of creating a response is by calling api()
method and passing the parameters directly to the helper function. Again, it is up to you how you better want to use it.
Check the below code example.
public function index() { $users = User::all(); return api(200, 'Users list', $users); }
This is the result:
{ "STATUS": 200, "MESSAGE": "users list", "DATA": [ {"name": "Obay Hamed"} ] }
Helper functions
The package ships with a group of functions that will help you to speed up your development process. For example, you could call directly api()->ok()
if the response was successful, instead of building the response.
function ok()
The ok()
function can be used without passing any parameters, it will defaulted the status code to 200
and use the default message from the configuration file.
return api()->ok();
Result:
{ "STATUS": 200, "MESSAGE": "Process is successfully completed", "DATA": {} }
Or you could pass to the function a custom message and the data you need. In this case, as mentioned before, the ok()
status code will be defaulted to 200.
$users = User::all(); return api()->ok("User list", $users);
Result:
{ "STATUS": 200, "MESSAGE": "User list", "DATA": [ {"name": "Obay Hamed"} ] }
function notFound()
The notFound()
function, as its name states, should be used for the case when the resource is not found and the status code will be defaulted to 404
. You could pass a custom message to this function otherwise it will use the default message from the configuration file.
return api()->notFound();
function validation()
The validation()
function can be used on the case of a validation error exist, throwing a 422 status code by default. It accepts two mandatory parameters: a message and an array of errors, and as many extra parameters you need (we recommend a key value array format). If the message is empty, then the default message will be used instead.
return api()->validation('These fields are required.', ['name', 'lastName']);
function error()
The error()
function can be used when an internal server error occurs throwing a 500 status code by default. It accepts two mandatory parameters: a message and an array of errors, and as many extra parameters you need (we recommend a key value array format). If the message is empty, then the default message will be used instead.
Configuration
JSON Response Labels
If you need to customize the default messages or the json response labels, you can do it directly on the api.php
configuration file.
Matching Status Codes
By default, all API responses return a 200 OK HTTP status header. If you'd like the status header to match the Response's status, set the matchstatus
configuration to true
Include The Count Of Data
You can optionally include the count of the DATA
portion of the response, by setting includeDataCount
to true
in the api.php
configuration file. You can also override the label, if desired, by updating the label in thekeys
array of the configuration file.
{ "STATUS": "200", "MESSAGE": "User Profile data", "DATA": [ ... ], "DATACOUNT": 6 }
Contributing
We will be happy if we see PR from you.
License
The API Response is a free package released under the MIT License.