# rajeshmk/laravel-api-exceptions architecture

> Architecture diagram of the GitHub repository rajeshmk/laravel-api-exceptions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rajeshmk/laravel-api-exceptions
- Repository: https://github.com/rajeshmk/laravel-api-exceptions

## Overview

1. **What this repo is**
   - This is a **Laravel package**, not an application.
   - Its job is to provide a reusable set of **API exception classes** that can be thrown from any Laravel app and automatically turn into JSON HTTP error responses.

2. **Package boundary and integration point**
   - The main integration surface is `src/ApiExceptionsServiceProvider.php`.
   - Laravel auto-discovers this provider, so the package wires itself into the host app without manual registration.
   - The provider’s main architectural role is to register package resources such as translations and any exception-response behavior.

3. **Core abstraction**
   - `src/Base/ApiBaseException.php` is the central base type.
   - All concrete exceptions inherit from it, which gives the package a single place to define common behavior such as:
     - message resolution
     - HTTP status selection
     - `Responsable` response conversion
   - This is the key boundary between “throwing an exception” and “returning an API response.”

4. **Response flow**
   - The intended flow is: application code throws one of these exceptions → Laravel catches it through normal exception handling → the exception itself produces a JSON response because it implements `Responsable`.
   - The README shows the response shape as:
     - `{ "error": { "message": "..." } }`
   - This keeps response formatting inside the exception layer instead of spreading it across controllers.

5. **HTTP status exception family**
   - `src/Http/*` contains generic HTTP status exceptions such as `BadRequestException`, `UnauthorizedException`, `ForbiddenException`, `NotFoundException`, `ConflictException`, `UnprocessableEntityException`, `TooManyRequestsException`, and `ServiceUnavailableException`.
   - These are the “primitive” API errors: thin wrappers around a specific HTTP status code, used when the error is not domain-specific.

6. **Auth-related exceptions**
   - `src/Auth/*` models authentication and authorization failures:
     - invalid or expired token
     - permission denied
     - authentication required
     - 2FA missing / unverified / failed
   - This subsystem is conceptually separate from generic HTTP errors because it encodes common security states that apps frequently need to map to 401/403-style responses.

7. **Domain-oriented helpers**
   - `src/General/*` contains reusable application-domain errors such as:
     - file upload failures
     - unsupported file types
     - file size limits
     - duplicate resources
     - country code lookup failures
     - OTP failures
   - `src/Model/*` focuses on persistence-layer operations:
     - model not found
     - create/update/delete failures
   - These exceptions are higher-level than raw HTTP codes and are intended to produce consistent, human-readable API messages.

8. **Validation-specific errors**
   - `src/Validation/CustomValidationException.php` is a dedicated bucket for validation scenarios that do not fit Laravel’s default validation response path.
   - This keeps validation-oriented API failures distinct from general bad-request errors.

9. **Message generation and consistency**
   - The package supports default message generation when a custom message is not supplied, inferred from the exception class name.
   - Several classes expose factory methods like `for(...)`, `forModel(...)`, or `forFile(...)` so calling code can build consistent messages without repeating formatting logic.
   - This is a message-construction layer, not just a status-code layer.

10. **Localization boundary**
   - `resources/lang/en/messages.php` provides built-in English translations/defaults.
   - The README indicates these can be overridden in the host app under `resources/lang/{locale}/vendor/api-exceptions`.
   - So the package separates core exception behavior from localized wording.

11. **Extensibility**
   - The package supports custom exceptions by extending `Hatchyu\ApiExceptions\Base\ApiBaseException` and overriding the HTTP code behavior.
   - That means the base class is the main extension point, while the named exception classes are convenience presets.

12. **Support files**
   - `stubs/laravel-helpers.php` is support infrastructure rather than runtime domain logic, likely for IDE/static-analysis helper definitions.
   - `composer.json` and the package structure indicate a standard Composer-distributed Laravel library.

13. **Notable deprecation**
   - `DocumentUploadException` exists but is marked deprecated in favor of `FileUploadException`.
   - That suggests the library keeps backward compatibility while steering consumers toward a newer, more general exception shape.

14. **How to diagram it**
   - A good architecture diagram would show:
     - host Laravel app code on the left throwing exceptions
     - this package in the middle with a shared base exception and several exception families
     - Laravel’s response pipeline on the right receiving a `Responsable` exception and emitting JSON
     - a translation layer underneath feeding default/localized messages
     - the service provider as the package’s bootstrap entry point

Main entry points: [`src/Base/ApiBaseException.php`](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Base/ApiBaseException.php) (Base exception), [`src/Http`](https://github.com/rajeshmk/laravel-api-exceptions/tree/main/src/Http) (HTTP errors), [`src/General`](https://github.com/rajeshmk/laravel-api-exceptions/tree/main/src/General) (General errors), [`src/ApiExceptionsServiceProvider.php`](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/ApiExceptionsServiceProvider.php) (Service provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Integration"]
  node_host_app["Host app<br/>consumer"]
  node_laravel_framework["Laravel<br/>runtime"]
  node_provider["Service provider<br/>bootstrap"]
end

subgraph group_core["Core"]
  node_api_base["Base exception<br/>responsable base"]
end

subgraph group_families["Exception families"]
  node_http_family["HTTP errors<br/>status presets"]
  node_auth_family["Auth errors<br/>security presets"]
  node_general_family["General errors<br/>domain presets"]
  node_model_family["Model errors<br/>persistence presets"]
  node_validation_exception["Validation error<br/>validation preset"]
  node_bad_request["Bad request<br/>http 400"]
  node_not_found["Not found<br/>http 404"]
  node_unauthorized["Unauthorized<br/>http 401"]
  node_file_upload["File upload<br/>domain preset"]
  node_duplicate_resource["Duplicate resource<br/>domain preset"]
  node_model_not_found["Model not found<br/>persistence preset"]
end

subgraph group_resources["Resources"]
  node_messages_lang["English messages<br/>translations<br/>[messages.php]"]
  node_helpers_stub["Helpers stub<br/>support"]
end

node_host_app -->|"auto-discovers"| node_provider
node_provider -->|"registers behavior"| node_api_base
node_api_base -->|"produces response"| node_laravel_framework
node_host_app -->|"throws"| node_api_base
node_api_base -->|"resolves defaults"| node_messages_lang
node_messages_lang -.->|"overridable by"| node_host_app
node_http_family -->|"inherits"| node_api_base
node_auth_family -->|"inherits"| node_api_base
node_general_family -->|"inherits"| node_api_base
node_model_family -->|"inherits"| node_api_base
node_validation_exception -->|"inherits"| node_api_base
node_bad_request -->|"member of"| node_http_family
node_not_found -->|"member of"| node_http_family
node_unauthorized -->|"member of"| node_http_family
node_file_upload -->|"member of"| node_general_family
node_duplicate_resource -->|"member of"| node_general_family
node_model_not_found -->|"member of"| node_model_family
node_helpers_stub -.->|"supports tooling"| node_host_app

click node_provider "https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/ApiExceptionsServiceProvider.php"
click node_api_base "https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Base/ApiBaseException.php"
click node_messages_lang "https://github.com/rajeshmk/laravel-api-exceptions/blob/main/resources/lang/en/messages.php"
click node_helpers_stub "https://github.com/rajeshmk/laravel-api-exceptions/blob/main/stubs/laravel-helpers.php"
click node_http_family "https://github.com/rajeshmk/laravel-api-exceptions/tree/main/src/Http"
click node_auth_family "https://github.com/rajeshmk/laravel-api-exceptions/tree/main/src/Auth"
click node_general_family "https://github.com/rajeshmk/laravel-api-exceptions/tree/main/src/General"
click node_model_family "https://github.com/rajeshmk/laravel-api-exceptions/tree/main/src/Model"
click node_validation_exception "https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Validation/CustomValidationException.php"
click node_bad_request "https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Http/BadRequestException.php"
click node_not_found "https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Http/NotFoundException.php"
click node_unauthorized "https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Http/UnauthorizedException.php"
click node_file_upload "https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/General/FileUploadException.php"
click node_duplicate_resource "https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/General/DuplicateResourceException.php"
click node_model_not_found "https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Model/ModelNotFoundException.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_host_app,node_laravel_framework,node_provider toneBlue
class node_api_base toneAmber
class node_http_family,node_auth_family,node_general_family,node_model_family,node_validation_exception,node_bad_request,node_not_found,node_unauthorized,node_file_upload,node_duplicate_resource,node_model_not_found toneMint
class node_messages_lang,node_helpers_stub toneRose
```

## Components

### Integration

How Laravel discovers and executes the package

- **Host app**: consumer · Any Laravel application that throws these exceptions
- **Laravel**: runtime · Framework exception handling and response pipeline
- [Service provider](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/ApiExceptionsServiceProvider.php): bootstrap · Auto-discovered package entry point · `src/ApiExceptionsServiceProvider.php`

### Core

Shared exception behavior and extension point

- [Base exception](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Base/ApiBaseException.php): responsable base · Shared message, status, and JSON response behavior · `src/Base/ApiBaseException.php`

### Exception families

Concrete exception presets grouped by concern

- [HTTP errors](https://github.com/rajeshmk/laravel-api-exceptions/tree/main/src/Http): status presets · Generic HTTP status exceptions · `src/Http`
- [Auth errors](https://github.com/rajeshmk/laravel-api-exceptions/tree/main/src/Auth): security presets · Authentication and authorization failures · `src/Auth`
- [General errors](https://github.com/rajeshmk/laravel-api-exceptions/tree/main/src/General): domain presets · Reusable application-level failures · `src/General`
- [Model errors](https://github.com/rajeshmk/laravel-api-exceptions/tree/main/src/Model): persistence presets · Create, update, delete, and not-found failures · `src/Model`
- [Validation error](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Validation/CustomValidationException.php): validation preset · Custom validation response exception · `src/Validation/CustomValidationException.php`
- [Bad request](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Http/BadRequestException.php): http 400 · Primitive client error preset · `src/Http/BadRequestException.php`
- [Not found](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Http/NotFoundException.php): http 404 · Resource-missing preset · `src/Http/NotFoundException.php`
- [Unauthorized](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Http/UnauthorizedException.php): http 401 · Authentication preset · `src/Http/UnauthorizedException.php`
- [File upload](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/General/FileUploadException.php): domain preset · Upload and file constraint failures · `src/General/FileUploadException.php`
- [Duplicate resource](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/General/DuplicateResourceException.php): domain preset · Resource conflict preset · `src/General/DuplicateResourceException.php`
- [Model not found](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/src/Model/ModelNotFoundException.php): persistence preset · Missing model preset · `src/Model/ModelNotFoundException.php`

### Resources

Localization and support files

- [English messages](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/resources/lang/en/messages.php): translations · Default localized message strings · `resources/lang/en/messages.php`
- [Helpers stub](https://github.com/rajeshmk/laravel-api-exceptions/blob/main/stubs/laravel-helpers.php): support · IDE/static-analysis helper definitions · `stubs/laravel-helpers.php`

## Connections

- Host app → Service provider: auto-discovers · Laravel loads the package bootstrapping entry point
- Service provider → Base exception: registers behavior · Provider wires package exception behavior into the host app
- Base exception → Laravel: produces response · Base exception converts itself into a Responsable JSON response
- Host app → Base exception: throws · Application code throws package exceptions
- Base exception → English messages: resolves defaults · Default wording comes from package translations
- English messages → Host app: overridable by · Host app can publish or override localized messages
- HTTP errors → Base exception: inherits · Generic HTTP status exceptions extend the shared base
- Auth errors → Base exception: inherits · Auth and permission failures extend the shared base
- General errors → Base exception: inherits · Domain-level helpers extend the shared base
- Model errors → Base exception: inherits · Persistence failures extend the shared base
- Validation error → Base exception: inherits · Validation-specific exception extends the shared base
- Bad request → HTTP errors: member of · Concrete HTTP preset
- Not found → HTTP errors: member of · Concrete HTTP preset
- Unauthorized → HTTP errors: member of · Concrete HTTP preset
- File upload → General errors: member of · Concrete general-domain preset
- Duplicate resource → General errors: member of · Concrete general-domain preset
- Model not found → Model errors: member of · Concrete persistence preset
- Helpers stub → Host app: supports tooling · Provides helper definitions for developer ergonomics