This package provides an easy way to manage and handle error response for JSON API's.
You can install the package via composer:
composer require 3sidedcube/laravel-api-errors
There are 2 ways of generating an API error response:
This package provides an exception called ApiErrorException
which you can extend. There are 3 methods which can
be set (2 of which are required):
code()
- This is a short string indicating the error code (required).message()
- A human-readable message providing more details about the error (required).statusCode()
- This HTTP status code of the error response. By default, this is set to 400 and is optional.
Once you have an exception, you can use the fromException()
method to generate an API error response:
use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;
use ThreeSidedCube\LaravelApiErrors\Exceptions\ApiErrorException;
class UserBannedException extends ApiErrorException
{
/**
* A short error code describing the error.
*
* @return string
*/
public function code(): string
{
return 'user_account_banned';
}
/**
* A human-readable message providing more details about the error.
*
* @return string
*/
public function message(): string
{
return 'User account banned.';
}
/**
* The api error status code.
*
* @return int
*/
public function statusCode(): int
{
return 403;
}
}
$exception = new UserBannedException();
// This will return an instance of JsonResponse
$response = ApiErrorResponse::fromException($exception);
Returning this response would generate the following json response:
{
"error": {
"code": "user_account_banned",
"message": "User account banned."
}
}
If you want to automatically return the JSON response from the exception, you can add the exception to the $dontReport
array in your app/Exceptions/Handler.php
like so:
use ThreeSidedCube\LaravelApiErrors\Exceptions\ApiErrorException;
protected $dontReport = [
ApiErrorException::class,
];
Alternatively you can use the create()
method to create an API error response:
use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;
// This will return an instance of JsonResponse
$response = ApiErrorResponse::create('user_account_banned', 'User account banned.', 403);
Returning this response would generate the following json response:
{
"error": {
"code": "user_account_banned",
"message": "User account banned."
}
}
If you would like to pass additional "meta" data to the response, you can use the meta()
method or pass an array to
the create method like so:
use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;
use ThreeSidedCube\LaravelApiErrors\Exceptions\ApiErrorException;
class UserBannedException extends ApiErrorException
{
/**
* A short error code describing the error.
*
* @return string
*/
public function code(): string
{
return 'user_account_banned';
}
/**
* A human-readable message providing more details about the error.
*
* @return string
*/
public function message(): string
{
return 'User account banned.';
}
/**
* The api error status code.
*
* @return int
*/
public function statusCode(): int
{
return 403;
}
/**
* Any additional metadata to be included in the response.
*
* @return array
*/
public function meta(): array
{
return [
'foo' => 'bar',
];
}
}
$exception = new UserBannedException();
// This will return an instance of JsonResponse
$response = ApiErrorResponse::fromException($exception);
or
use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;
// This will return an instance of JsonResponse
$response = ApiErrorResponse::create('user_account_banned', 'User account banned.', 403, ['foo' => 'bar']);
Returning this response would generate the following json response:
{
"error": {
"code": "user_account_banned",
"message": "User account banned.",
"meta": {
"foo": "bar"
}
}
}
composer test
Please see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
Laravel API Errors is open-sourced software licensed under the MIT license.