PHPackages jenky/hades - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. jenky/hades ActiveLibrary[API Development](/categories/api) jenky/hades =========== Error response formatter for Laravel app 3.0.0(1y ago)092MITPHPPHP ^8.1CI passing Since Feb 24Pushed 1y ago1 watchersCompare [ Source](https://github.com/jenky/hades)[ Packagist](https://packagist.org/packages/jenky/hades)[ Docs](https://github.com/jenky/hades)[ RSS](/packages/jenky-hades/feed)WikiDiscussions master Synced 1w ago READMEChangelog (8)Dependencies (8)Versions (12)Used By (0) Hades ===== [](#hades) [![Latest Version on Packagist](https://camo.githubusercontent.com/7a04e2834469e49d8941daaf5311872121ef7ec4fbbbca54b3f3d558238a7067/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a656e6b792f68616465732e7376673f6c6f676f3d7061636b6167697374267374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/jenky/hades)[![Github Actions](https://camo.githubusercontent.com/a5bf25f7093b5ad0c279b731f6f89ee419a426cc8da3a632732b75e62670103e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6a656e6b792f68616465732f74657374696e672e796d6c3f6272616e63683d6d6173746572266c6162656c3d616374696f6e73266c6f676f3d676974687562267374796c653d666f722d7468652d6261646765)](https://github.com/jenky/hades/actions)[![Codecov](https://camo.githubusercontent.com/52df3e6767c6cbc531db9c55f3dbacd6b5b94401453a66573d61486e79249329/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f6a656e6b792f68616465733f6c6f676f3d636f6465636f76267374796c653d666f722d7468652d6261646765)](https://codecov.io/gh/jenky/hades)[![Total Downloads](https://camo.githubusercontent.com/27371ae11cf0d304246d4a0469f18546a6a522d24dedb28eafbdc77a26f49ec4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a656e6b792f68616465732e7376673f7374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/jenky/hades)[![Software License](https://camo.githubusercontent.com/9897f4467850972a38c7db9a4d38280b8fcdac0ada00e9c8c0a72ecfa8551653/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666f722d7468652d6261646765)](LICENSE.md) Dealing with errors when building an API can be a pain. Instead of manually building error responses you can simply throw an exception and the Hades will handle the response for you. Installation ------------ [](#installation) You may use Composer to install this package into your Laravel project: ``` $ composer require jenky/hades ``` Configuration ------------- [](#configuration) ### Generic Error Response Format [](#generic-error-response-format) By default all thrown exceptions will be transformed to the following format: ``` { 'message' => ':message', // The exception message 'status' => ':status_code', // The corresponding HTTP status code, default to 500 'errors' => ':errors', // The error bag, typically validation error messages 'code' => ':code', // The exception code 'debug' => ':debug', // The debug information } ``` > The debug information only available when application is not in `production` environment and `debug` mode is on. Example: ``` curl --location --request GET 'http://myapp.test/api/user' \ --header 'Accept: application/json' ``` ``` { "message": "Unauthenticated.", "type": "AuthenticationException", "status": 401, "code": 0, } ``` > Any keys that aren't replaced with corresponding values will be removed from the final response. Formatting Exception -------------------- [](#formatting-exception) If you would like to use different error format for your application, you should call the `Hades::errorFormat()` method in the `boot` method of your `App\Providers\AppServiceProvider` class: ``` use Jenky\Hades\Hades; /** * Bootstrap any application services. * * @return void */ public function boot() { Hades::errorFormat([ 'message' => ':message', 'error_description' => ':error', ]); } ``` ### Customizing Exception Response [](#customizing-exception-response) Hades uses [`api-error`](https://github.com/jenky/api-error) internally. Please see the [exception transformations](https://github.com/jenky/api-error?tab=readme-ov-file#exception-transformations) to see how it works. To add a custom transformers, you can use the config file ``` // configs/hades.php return [ 'transformers' => [ App\Exceptions\Transformers\MyCustomTransformer::class, ], ]; ``` Alternatively, if Laravel can't inject your custom exception transformer, you may wish to register the exception transformer with the `api_error.exception_transformer` tag in your service provider. Typically, you should call this method from the `register` method of your application's `App\Providers\AppServiceProvider` class: ``` use App\Exceptions\Transformers\MyCustomTransformer; use Illuminate\Contracts\Debug\ExceptionHandler; public function register(): void { $this->app->bind(MyCustomTransformer::class, static fn () => 'your binding logic'); $this->app->tag('api_error.exception_transformer', MyCustomTransformer::class); } ``` Content Negotiation ------------------- [](#content-negotiation) ### Forcing the JSON Response [](#forcing-the-json-response) By default, Laravel expects the request should contains header `Accept` with the MIME type `application/json` or custom MIME with `json` format such as `application/vnd.myapp.v1+json` in order to return JSON response. Otherwise your may get redirected to login page if the credentials are invalid or missing/passing invalid authorization token. While this is a good design practice, sometimes you may wish to attach the header to request automatically, such as using Laravel as pure API backend. To do this, you should call the `Hades::forceJsonOutput()` method within the `boot` method of your `App\Providers\AppServiceProvider`. ``` use Jenky\Hades\Hades; public function boot(): void { Hades::forceJsonOutput(); } ``` Hades will add the header `Accept: application/json` to all [incoming API requests](#identify-api-requests). If you want to use custom MIME type, you may use the `withMimeType` to specify the MIME type: ``` Hades::forceJsonOutput() ->withMimeType('application/vnd.myapp.v1+json'); ``` ### Identify API Requests [](#identify-api-requests) In order to force the response to return JSON output, Hades needs to identify the incoming request so it doesn't add the `Accept` header on your normal HTML pages. By default, all your API routes defined in `routes/api.php` have `/api` URI prefix automatically applied. Hades will inspects the incoming request URI and determines it's URI matches the `/api` prefix. To customize this behavior, you may pass the closure to `Hades::forceJsonOutput()` to instruct Hades how to identify the incoming request: ``` use Illuminate\Http\Request; Hades::forceJsonOutput(static function (Request $request) { return $request->is('api/v1/*'); }); ``` If your application is built solely for API use, you can configure the request to always return a JSON response. ``` use Illuminate\Http\Request; Hades::forceJsonOutput(static fn () => true); ``` Change log ---------- [](#change-log) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Testing ------- [](#testing) ``` $ composer test ``` Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) and [CODE\_OF\_CONDUCT](CODE_OF_CONDUCT.md) for details. Security -------- [](#security) If you discover any security related issues, please email instead of using the issue tracker. Credits ------- [](#credits) - [Lynh](https://github.com/jenky) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 36 — LowBetter than 82% of packages Maintenance45 Moderate activity, may be stable Popularity10 Limited adoption so far Community7 Small or concentrated contributor base Maturity68 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~164 days Recently: every ~190 days Total 10 Last Release 427d ago Major Versions 1.x-dev → 2.0.02023-02-15 2.x-dev → 3.0.02025-03-17 PHP version history (3 changes)1.0.0PHP ^7.2|^8.0 2.0.0PHP ^8.0 3.0.0PHP ^8.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/783e915bb411d566e8f1035f197842db5e870a2a995b3943bcbe5db2f9abf09b?d=identicon)[Milano](/maintainers/Milano) --- Top Contributors [![jenky](https://avatars.githubusercontent.com/u/1808758?v=4)](https://github.com/jenky "jenky (69 commits)") --- Tags apierrorjsonlaravelphpapilaravelhadesjenkyerror format ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer ### Embed Badge ![Health badge](/badges/jenky-hades/health.svg) ``` [![Health](https://phpackages.com/badges/jenky-hades/health.svg)](https://phpackages.com/packages/jenky-hades) ``` ### Alternatives [andreaselia/laravel-api-to-postman Generate a Postman collection automatically from your Laravel API 1.0k586.2k3](/packages/andreaselia-laravel-api-to-postman)[mollie/laravel-mollie Mollie API client wrapper for Laravel & Mollie Connect provider for Laravel Socialite 3624.1M28](/packages/mollie-laravel-mollie)[api-platform/laravel API Platform support for Laravel 59126.4k6](/packages/api-platform-laravel)[dragon-code/laravel-json-response Automatically always return a response in JSON format 1118.6k1](/packages/dragon-code-laravel-json-response)[vinelab/api-manager Laravel API Manager Package - beatify and unify your responses with the least effort possible. 392.1k](/packages/vinelab-api-manager)[surface/laravel-webfinger A Laravel package to create an ActivityPub webfinger. 113.8k](/packages/surface-laravel-webfinger) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)