3sidedcube/laravel-api-errors

A lightweight package for handling API error responses.

v1.0.0 2021-11-26 11:04 UTC

This package is auto-updated.

Last update: 2021-11-26 11:51:13 UTC


README

Latest Version on Packagist Total Downloads GitHub Actions

This package provides an easy way to manage and handle error response for JSON API's.

Installation

You can install the package via composer:

composer require 3sidedcube/laravel-api-errors

Usage

There are 2 ways of generating an API error response:

API Error Exception

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 Cube\LaravelApiErrors\ApiErrorResponse;
use Cube\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."
    }
}

Automatically returning the exception response

If you want to automatically return the JSON response from the exception, you can add the exception to the $doNotReport array in your app/Exceptions/Handler.php like so:

use Cube\LaravelApiErrors\Exceptions\ApiErrorException;

protected $dontReport = [
    ApiErrorException::class,
];

Passing data directly

Alternatively you can use the create() method to create an API error response:

use Cube\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."
    }
}

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

License

Laravel Horizon is open-sourced software licensed under the MIT license.