README

Global error/exception handler for Laravel APIs. Provides standardized JSON error responses with configurable exception mappings.

Features

• Global exception handling for all API errors
• Consistent JSON error response format
• Configurable exception mappings (add your own exceptions)
• Built-in handling for common Laravel exceptions
• Customizable response structure
• First-error or all-errors validation format
• Environment-based debug info (trace & error details)
• Translation support for error messages
• Base FormRequest class for consistent validation errors

Requirements

• PHP 8.2+
• Laravel 11.0+ or 12.0+

Installation

composer require jeromejhipolito/laravel-global-error-formatter

The package will auto-register its service provider.

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=global-error-formatter-config

Quick Start

Register in bootstrap/app.php

use JeromeJHipolito\GlobalErrorFormatter\GlobalErrorFormatter;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions) {
        GlobalErrorFormatter::register($exceptions);
    })
    ->create();

That's it! All exceptions in API requests will now return consistent JSON responses.

Response Format

{
    "status": "error",
    "message": "Resource not found.",
    "errors": null,
    "trace": null
}

Environment-Based Error Details

The package automatically shows/hides error details based on your environment:

// config/global-error-formatter.php

// Stack trace - only shown in debug mode
'include_trace' => env('GLOBAL_ERROR_INCLUDE_TRACE', env('APP_DEBUG', false)),

// Error details (exception message) - only shown in debug mode
'include_error_details' => env('GLOBAL_ERROR_DETAILS', env('APP_DEBUG', false)),

Development (APP_DEBUG=true):

{
    "status": "error",
    "message": "Something went wrong.",
    "errors": "SQLSTATE[42S02]: Base table or view not found...",
    "trace": [...]
}

Production (APP_DEBUG=false):

{
    "status": "error",
    "message": "Something went wrong."
}

Adding Custom Exceptions

Via Configuration

// config/global-error-formatter.php
'exceptions' => [
    \App\Exceptions\PaymentException::class => [
        'status' => 402,
        'message' => 'Payment required.',
    ],
    \App\Exceptions\CouponException::class => [
        'status' => 400,
        'message' => null,  // Uses exception's getMessage()
    ],
],

Programmatically

use JeromeJHipolito\GlobalErrorFormatter\GlobalErrorFormatter;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions) {
        $formatter = app(GlobalErrorFormatter::class);

        $formatter
            ->addException(PaymentException::class, 402, 'Payment required.')
            ->addException(CouponException::class, 400);  // Uses exception message

        $exceptions->render(function (Throwable $e, Request $request) use ($formatter) {
            if ($request->expectsJson()) {
                return $formatter->format($e);
            }
            return null;
        });
    })
    ->create();

Built-in Exception Handling

Using BaseFormRequest

Extend BaseFormRequest for consistent validation error responses:

use JeromeJHipolito\GlobalErrorFormatter\BaseFormRequest;

class CreateUserRequest extends BaseFormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'email' => 'required|email|unique:users',
            'password' => 'required|min:8',
        ];
    }
}

Validation errors will automatically use the configured format.

Configuration Options

Response Keys

Customize the JSON response structure:

'response_keys' => [
    'status' => 'status',      // Change to 'result', 'success', etc.
    'message' => 'message',    // Change to 'msg', 'error', etc.
    'errors' => 'errors',      // Change to 'details', 'data', etc.
    'trace' => 'trace',        // Change to 'stack', 'debug', etc.
],

Status Values

Customize the status field values:

'status_values' => [
    'success' => 'success',
    'error' => 'error',        // Change to 'failed', 'failure', etc.
],

Validation Format

Choose how validation errors are returned:

// 'first' - Only the first error message (default)
'validation_format' => 'first',

// 'all' - All errors with field names
'validation_format' => 'all',

First format response:

{
    "status": "error",
    "message": "The email field is required."
}

All format response:

{
    "status": "error",
    "message": "Validation failed.",
    "errors": {
        "email": ["The email field is required."],
        "password": ["The password must be at least 8 characters."]
    }
}

Translation Support

// Pass messages through trans() helper
'translate_messages' => true,

This allows you to create translation files for error messages:

// lang/ja/messages.php
return [
    'Resource not found.' => 'リソースが見つかりません。',
    'Validation failed.' => '検証に失敗しました。',
];

Conditional Registration

Only handle specific requests:

GlobalErrorFormatter::register($exceptions, function (Throwable $e, Request $request) {
    // Only handle API routes
    return $request->is('api/*');
});

Override Default Messages

'defaults' => [
    'model_not_found' => [
        'status' => 404,
        'message' => 'The requested item was not found.',
    ],
    'authentication' => [
        'status' => 401,
        'message' => 'Please log in to continue.',
    ],
    // ... other defaults
],

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.

Credits

• Jerome Hipolito