{"id":23882306,"url":"https://github.com/jenky/hades","last_synced_at":"2026-05-06T13:33:11.788Z","repository":{"id":40394032,"uuid":"341153919","full_name":"jenky/hades","owner":"jenky","description":"API error formatting handler for Laravel app","archived":false,"fork":false,"pushed_at":"2023-08-10T08:20:10.000Z","size":54,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-10T18:22:35.409Z","etag":null,"topics":["api","error","json","laravel","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-02-22T09:59:41.000Z","updated_at":"2024-04-15T03:27:19.374Z","dependencies_parsed_at":"2024-04-15T03:27:14.946Z","dependency_job_id":"a138091f-758a-4f8e-bf69-8931b4583702","html_url":"https://github.com/jenky/hades","commit_stats":{"total_commits":48,"total_committers":2,"mean_commits":24.0,"dds":0.04166666666666663,"last_synced_commit":"592064c95d4ef9e159edcd6f63ce01d58c636927"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenky%2Fhades","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenky%2Fhades/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenky%2Fhades/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenky%2Fhades/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenky","download_url":"https://codeload.github.com/jenky/hades/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240255333,"owners_count":19772598,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","error","json","laravel","php"],"created_at":"2025-01-04T02:53:20.154Z","updated_at":"2026-05-06T13:33:11.782Z","avatar_url":"https://github.com/jenky.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hades\n\n[![Latest Version on Packagist][ico-version]][link-packagist]\n[![Github Actions][ico-gh-actions]][link-gh-actions]\n[![Codecov][ico-codecov]][link-codecov]\n[![Total Downloads][ico-downloads]][link-downloads]\n[![Software License][ico-license]](LICENSE.md)\n\nDealing 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.\n\n## Installation\n\nYou may use Composer to install this package into your Laravel project:\n\n``` bash\n$ composer require jenky/hades\n```\n\n## Configuration\n\n### Generic Error Response Format\n\nBy default all thrown exceptions will be transformed to the following format:\n\n```js\n{\n    'message' =\u003e ':message', // The exception message\n    'status' =\u003e ':status_code', // The corresponding HTTP status code, default to 500\n    'errors' =\u003e ':errors', // The error bag, typically validation error messages\n    'code' =\u003e ':code', // The exception code\n    'debug' =\u003e ':debug', // The debug information\n}\n```\n\n\u003e The debug information only available when application is not in `production` environment and `debug` mode is on.\n\nExample:\n\n```bash\ncurl --location --request GET 'http://myapp.test/api/user' \\\n--header 'Accept: application/json'\n```\n\n```js\n{\n  \"message\": \"Unauthenticated.\",\n  \"type\": \"AuthenticationException\",\n  \"status\": 401,\n  \"code\": 0,\n}\n```\n\n\u003e Any keys that aren't replaced with corresponding values will be removed from the final response.\n\n## Formatting Exception\n\nIf 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:\n\n```php\nuse Jenky\\Hades\\Hades;\n\n/**\n * Bootstrap any application services.\n *\n * @return void\n */\npublic function boot()\n{\n    Hades::errorFormat([\n        'message' =\u003e ':message',\n        'error_description' =\u003e ':error',\n    ]);\n}\n```\n\n### Customizing Exception Response\n\nHades 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.\n\nTo add a custom transformers, you can use the config file\n\n```php\n// configs/hades.php\n\nreturn [\n\n    'transformers' =\u003e [\n        App\\Exceptions\\Transformers\\MyCustomTransformer::class,\n    ],\n\n];\n```\n\nAlternatively, 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:\n\n```php\nuse App\\Exceptions\\Transformers\\MyCustomTransformer;\nuse Illuminate\\Contracts\\Debug\\ExceptionHandler;\n\npublic function register(): void\n{\n    $this-\u003eapp-\u003ebind(MyCustomTransformer::class, static fn () =\u003e 'your binding logic');\n\n    $this-\u003eapp-\u003etag('api_error.exception_transformer', MyCustomTransformer::class);\n}\n```\n\n## Content Negotiation\n\n### Forcing the JSON Response\n\nBy 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.\n\nWhile 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`.\n\n```php\nuse Jenky\\Hades\\Hades;\n\npublic function boot(): void\n{\n    Hades::forceJsonOutput();\n}\n```\n\nHades 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:\n\n```php\nHades::forceJsonOutput()\n    -\u003ewithMimeType('application/vnd.myapp.v1+json');\n```\n\n### Identify API Requests\n\nIn 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.\n\nBy 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.\n\nTo customize this behavior, you may pass the closure to `Hades::forceJsonOutput()` to instruct Hades how to identify the incoming request:\n\n```php\nuse Illuminate\\Http\\Request;\n\nHades::forceJsonOutput(static function (Request $request) {\n    return $request-\u003eis('api/v1/*');\n});\n```\n\nIf your application is built solely for API use, you can configure the request to always return a JSON response.\n\n```php\nuse Illuminate\\Http\\Request;\n\nHades::forceJsonOutput(static fn () =\u003e true);\n```\n\n## Change log\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Testing\n\n``` bash\n$ composer test\n```\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) and [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) for details.\n\n## Security\n\nIf you discover any security related issues, please email contact@lynh.me instead of using the issue tracker.\n\n## Credits\n\n- [Lynh][link-author]\n- [All Contributors][link-contributors]\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n\n[ico-version]: https://img.shields.io/packagist/v/jenky/hades.svg?logo=packagist\u0026style=for-the-badge\n[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=for-the-badge\n[ico-travis]: https://img.shields.io/travis/jenky/hades/master.svg?style=for-the-badge\n[ico-scrutinizer]: https://img.shields.io/scrutinizer/coverage/g/jenky/hades.svg?style=for-the-badge\n[ico-code-quality]: https://img.shields.io/scrutinizer/g/jenky/hades.svg?style=for-the-badge\n[ico-downloads]: https://img.shields.io/packagist/dt/jenky/hades.svg?style=for-the-badge\n[ico-gh-actions]: https://img.shields.io/github/actions/workflow/status/jenky/hades/testing.yml?branch=master\u0026label=actions\u0026logo=github\u0026style=for-the-badge\n[ico-codecov]: https://img.shields.io/codecov/c/github/jenky/hades?logo=codecov\u0026style=for-the-badge\n\n[link-packagist]: https://packagist.org/packages/jenky/hades\n[link-travis]: https://travis-ci.org/jenky/hades\n[link-scrutinizer]: https://scrutinizer-ci.com/g/jenky/hades/code-structure\n[link-code-quality]: https://scrutinizer-ci.com/g/jenky/hades\n[link-downloads]: https://packagist.org/packages/jenky/hades\n[link-author]: https://github.com/jenky\n[link-contributors]: ../../contributors\n[link-gh-actions]: https://github.com/jenky/hades/actions\n[link-codecov]: https://codecov.io/gh/jenky/hades\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenky%2Fhades","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenky%2Fhades","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenky%2Fhades/lists"}