rajeshmk/laravel-api-exceptions

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