3sidedcube/laravel-api-errors

A lightweight package for handling API error responses.

v1.3.1 2024-05-20 11:44 UTC

Requires

• php: ^8.0|^8.1|^8.2|^8.3
• illuminate/routing: ^8.0|^9.0|^10.0|^11.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.3
• orchestra/testbench: ^6.0|^7.0|^8.0|^9.0

MIT

• Ben Sherred

• 3sidedcube
• laravel-api-errors

README

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 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."
    }
}

Automatically returning the exception response

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,
];

Passing data directly

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."
    }
}

Additional data

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"
        }
    }
}

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• Ben Sherred
• All Contributors

License

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