README

A professional Laravel package for centralized API exception handling with unified response structure, status codes, and messages.

Features

🎯 Centralized Exception Handling: Single point of control for all API exceptions
📦 Unified Response Structure: Consistent JSON responses across all exceptions
🔒 Security First: Hides sensitive information in production
📝 Comprehensive Logging: Automatic logging of unhandled exceptions
🔧 Highly Customizable: Easy to extend and customize
🚀 Laravel 11+ Ready: Built for Laravel 11 and 12

Installation

Via Composer

composer require rawnod/laravel-exceptions

Manual Installation

If you're installing manually, add the package to your composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/rawnod/laravel-exceptions"
        }
    ],
    "require": {
        "rawnod/laravel-exceptions": "*"
    }
}

Then run:

composer install

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=exceptions-config

This will create config/exceptions.php where you can customize exception handling behavior.

Setup

Automatic Registration (Recommended)

By default, the package automatically registers the exception handler. No manual configuration is required!

The handler will automatically work for all routes matching the api_pattern (default: api/*).

To disable automatic registration, set in your .env:

EXCEPTIONS_AUTO_REGISTER=false

Manual Registration (Optional)

If you disabled automatic registration, you can manually register the exception handler in your bootstrap/app.php:

use Rawnod\Exceptions\ExceptionRenderer;
use Illuminate\Foundation\Configuration\Exceptions;

return Application::configure(basePath: dirname(__DIR__))
    // ... other configuration
    ->withExceptions(function (Exceptions $exceptions): void {
        $exceptions->render(function (\Throwable $e, $request) {
            if ($request->is('api/*')) {
                return app(ExceptionRenderer::class)->render($e);
            }
        });
    })->create();

Supported Exceptions

The package handles the following exception types:

HttpResponseException - Custom HTTP responses
ModelNotFoundException - Eloquent model not found
NotFoundHttpException - Route not found
MethodNotAllowedHttpException - HTTP method not allowed
ValidationException - Form validation errors
AuthenticationException - Unauthenticated requests
AuthorizationException - Unauthorized access
InvalidFilterQuery - Spatie QueryBuilder filter errors
InvalidIncludeQuery - Spatie QueryBuilder include errors
InvalidSortQuery - Spatie QueryBuilder sort errors
InvalidFieldQuery - Spatie QueryBuilder field errors
HttpExceptionInterface - All other HTTP exceptions
Generic exceptions - Fallback for unhandled exceptions

Usage

Once installed and configured, the exception handler will automatically catch and format all exceptions for API routes.

Language Files

The package includes built-in translations in English and Arabic. Translations are automatically loaded from the package.

Available Translation Keys

exceptions::exceptions.model_not_found - Model not found message
exceptions::exceptions.resource_not_found - Resource not found message
exceptions::exceptions.method_not_allowed - HTTP method not allowed
exceptions::exceptions.validation_failed - Validation failed message
exceptions::exceptions.unauthenticated - Authentication required
exceptions::exceptions.unauthorized - Authorization failed
exceptions::exceptions.server_error - Server error message
exceptions::exceptions.http_exception - Generic HTTP exception
exceptions::exceptions.bad_request - Bad request message

Customizing Translations

You can publish and customize the language files:

php artisan vendor:publish --tag=exceptions-lang

This will copy the language files to lang/vendor/exceptions/ where you can customize them.

Alternatively, you can override translations in your application's language files by creating files at:

lang/en/vendor/exceptions/exceptions.php
lang/ar/vendor/exceptions/exceptions.php

Response Structure

All exceptions return a consistent JSON structure using the rawnoq/laravel-api-response package format:

{
    "success": false,
    "message": "Error message",
    "data": null,
    "errors": {}
}

Requirements

PHP 8.2+
Laravel 11.0+ or 12.0+
rawnoq/laravel-api-response package

Optional Dependencies

spatie/laravel-query-builder - For query builder exception handling

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.

rawnoq / laravel-exceptions

Maintainers

Details