{"id":14974675,"url":"https://github.com/f9webltd/laravel-api-response-helpers","last_synced_at":"2025-05-14T06:08:18.693Z","repository":{"id":43864728,"uuid":"402430332","full_name":"f9webltd/laravel-api-response-helpers","owner":"f9webltd","description":":rocket: A simple package allowing for consistent API responses throughout your Laravel application","archived":false,"fork":false,"pushed_at":"2025-02-15T11:00:26.000Z","size":195,"stargazers_count":624,"open_issues_count":1,"forks_count":50,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-12T23:29:36.575Z","etag":null,"topics":["laravel","laravel-framework","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/f9webltd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-02T13:26:55.000Z","updated_at":"2025-03-28T10:11:32.000Z","dependencies_parsed_at":"2023-02-16T22:01:11.475Z","dependency_job_id":"98d2d4e3-f35d-4a7f-9e11-3c4ab286cd75","html_url":"https://github.com/f9webltd/laravel-api-response-helpers","commit_stats":{"total_commits":87,"total_committers":13,"mean_commits":"6.6923076923076925","dds":0.367816091954023,"last_synced_commit":"3b25a043fa4eeb007a51e6cf4d4dc4dfc951f9ca"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f9webltd%2Flaravel-api-response-helpers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f9webltd%2Flaravel-api-response-helpers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f9webltd%2Flaravel-api-response-helpers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f9webltd%2Flaravel-api-response-helpers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f9webltd","download_url":"https://codeload.github.com/f9webltd/laravel-api-response-helpers/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254079543,"owners_count":22011189,"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":["laravel","laravel-framework","php"],"created_at":"2024-09-24T13:50:54.527Z","updated_at":"2025-05-14T06:08:18.648Z","avatar_url":"https://github.com/f9webltd.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](https://banners.beyondco.de/Laravel%20API%20Response%20Helpers.png?theme=light\u0026packageManager=composer+require\u0026packageName=f9webltd%2Flaravel-api-response-helpers\u0026pattern=brickWall\u0026style=style_1\u0026description=Generate+consistent+API+responses+for+your+Laravel+application\u0026md=1\u0026showWatermark=0\u0026fontSize=100px\u0026images=code)\n\n[![Run Tests - Current](https://github.com/f9webltd/laravel-api-response-helpers/actions/workflows/run-tests.yml/badge.svg)](https://github.com/f9webltd/laravel-api-response-helpers/actions/workflows/run-tests.yml)\n[![Packagist Version](https://img.shields.io/packagist/v/f9webltd/laravel-api-response-helpers?style=flat-square)](https://packagist.org/packages/f9webltd/laravel-api-response-helpers)\n[![Total Downloads](https://poser.pugx.org/f9webltd/laravel-api-response-helpers/downloads.png)](https://packagist.org/packages/f9webltd/laravel-api-response-helpers)\n[![Packagist PHP Version](https://img.shields.io/packagist/php-v/f9webltd/laravel-api-response-helpers?style=flat-square)](https://packagist.org/packages/f9webltd/laravel-api-response-helpers)\n[![Packagist License](https://img.shields.io/packagist/l/f9webltd/laravel-api-response-helpers?style=flat-square)](https://packagist.org/packages/f9webltd/laravel-api-response-helpers)\n\n# Laravel API Response Helpers\n\nA simple package allowing for consistent API responses throughout your Laravel application.\n\n## Requirements\n\n- PHP `^8.0`\n- Laravel `^8.12`, `^9.0`, `^10.0`, `^11.0` or `^12.0`\n\n### Legacy Support\n\nFor PHP `^7.4` and Laravel `^6.0` / `^7.0` support, use package version [`^1.5`](https://github.com/f9webltd/laravel-api-response-helpers/tree/1.5.3)\n\n## Installation / Usage\n\n```bash\ncomposer require f9webltd/laravel-api-response-helpers\n```\n\nSimply reference the required trait within your controller:\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Api\\Controllers;\n\nuse F9Web\\ApiResponseHelpers;\nuse Illuminate\\Http\\JsonResponse;\n\nclass OrdersController\n{\n    use ApiResponseHelpers;\n\n    public function index(): JsonResponse\n    {\n        return $this-\u003erespondWithSuccess();\n    }\n}\n```\n\nOptionally, the trait could be imported within a base controller.\n\n## Available methods\n\n#### `respondNotFound(string|Exception $message, ?string $key = 'error')`\n\nReturns a `404` HTTP status code, an exception object can optionally be passed.\n\n#### `respondWithSuccess(array|Arrayable|JsonSerializable|null $contents = null)`\n\nReturns a `200` HTTP status code, optionally `$contents` to return as json can be passed. By default returns `['success' =\u003e true]`.\n\n#### `respondOk(string $message)`\n\nReturns a `200` HTTP status code\n\n#### `respondUnAuthenticated(?string $message = null)`\n\nReturns a `401` HTTP status code\n\n#### `respondForbidden(?string $message = null)`\n\nReturns a `403` HTTP status code\n\n#### `respondError(?string $message = null)`\n\nReturns a `400` HTTP status code\n\n#### `respondCreated(array|Arrayable|JsonSerializable|null $data = null)`\n\nReturns a `201` HTTP status code, with response optional data\n\n#### `respondNoContent(array|Arrayable|JsonSerializable|null $data = null)`\n\nReturns a `204` HTTP status code, with optional response data. Strictly speaking, the response body should be empty. However, functionality to optionally return data was added to handle legacy projects. Within your own projects, you can simply call the method, omitting parameters, to generate a correct `204` response i.e. `return $this-\u003erespondNoContent()`\n\n#### `setDefaultSuccessResponse(?array $content = null): self`\n\nOptionally, replace the default `['success' =\u003e true]` response returned by `respondWithSuccess` with `$content`. This method can be called from the constructor (to change default for all calls), a base API controller or place when required. \n\n`setDefaultSuccessResponse` is a fluent method returning `$this` allows for chained methods calls:\n\n```php\n$users = collect([10, 20, 30, 40]);\n\nreturn $this-\u003esetDefaultSuccessResponse([])-\u003erespondWithSuccess($users);\n```\n\nOr\n```php\npublic function __construct()\n{\n    $this-\u003esetDefaultSuccessResponse([]);\n}\n\n...\n\n$users = collect([10, 20, 30, 40]);\n\nreturn $this-\u003erespondWithSuccess($users);\n```\n\n\n## Use with additional object types\n\nIn addition to a plain PHP `array`, the following data types can be passed to relevant methods:\n\n- Objects implementing the Laravel `Illuminate\\Contracts\\Support\\Arrayable` contract\n- Objects implementing the native PHP `JsonSerializable` contract\n\nThis allows a variety of object types to be passed and converted automatically.\n\nBelow are a few common object types that can be passed.\n\n#### Laravel Collections - `Illuminate\\Support\\Collection`\n\n```php\n$users = collect([10, 20, 30, 40]);\n\nreturn $this-\u003erespondWithSuccess($users);\n```\n\n#### Laravel Eloquent Collections - `Illuminate\\Database\\Eloquent\\Collection`\n\n```php\n$invoices = Invoice::pending()-\u003eget();\n\nreturn $this-\u003erespondWithSuccess($invoices);\n```\n\n#### Laravel API Resources - `Illuminate\\Http\\Resources\\Json\\JsonResource`\n\nThis package is intended to be used **alongside** Laravel's  [API resources](https://laravel.com/docs/8.x/eloquent-resources) and in no way replaces them.\n\n```php\n$resource = PostResource::make($post);\n\nreturn $this-\u003erespondCreated($resource);\n```\n\n## Motivation\n\nEnsure consistent JSON API responses throughout an application. The motivation was primarily based on a very old inherited Laravel project. The project contained a plethora of methods/structures used to return an error:\n\n- `response()-\u003ejson(['error' =\u003e $error], 400)`\n- `response()-\u003ejson(['data' =\u003e ['error' =\u003e $error], 400)`\n- `response()-\u003ejson(['message' =\u003e $error], Response::HTTP_BAD_REQUEST)`\n- `response()-\u003ejson([$error], 400)`\n- etc.\n\nI wanted to add a simple trait that kept this consistent, in this case:\n\n`$this-\u003erespondError('Ouch')`\n\n## Upgrading\n\nPlease see [UPGRADING](UPGRADING.md) for details.\n\n## Contribution\n\nAny ideas are welcome. Feel free to submit any issues or pull requests.\n\n## Testing\n\n`composer test`\n\n## Security\n\nIf you discover any security related issues, please email rob@f9web.co.uk instead of using the issue tracker.\n\n## Credits\n\n- [Rob Allport](https://github.com/ultrono) for [F9 Web Ltd.](https://www.f9web.co.uk)\n- [All Contributors](https://github.com/f9webltd/laravel-api-response-helpers/graphs/contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff9webltd%2Flaravel-api-response-helpers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff9webltd%2Flaravel-api-response-helpers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff9webltd%2Flaravel-api-response-helpers/lists"}