|
| 1 | + |
| 2 | + |
| 3 | +[](https://packagist.org/packages/okriiza/laravel-api-response-formatter) |
| 4 | +[](https://packagist.org/packages/okriiza/laravel-api-response-formatter) |
| 5 | +[](https://opensource.org/licenses/MIT) |
| 6 | + |
| 7 | +# Laravel API Response Formatter |
| 8 | + |
| 9 | +`Laravel API Response Formatter` is a class that provides methods for formatting API responses in a standardized format. It simplifies the process of creating consistent and well-structured JSON responses in your API. |
| 10 | + |
| 11 | +## Requirements |
| 12 | + |
| 13 | +- PHP `^8.1 | ^8.2 | ^8.3` |
| 14 | +- Laravel 8, 9, 10, 11 or 12 |
| 15 | + |
| 16 | +## Installation |
| 17 | + |
| 18 | +You can install the package via composer: |
| 19 | + |
| 20 | +```bash |
| 21 | +composer require okriiza/laravel-api-response-formatter |
| 22 | +``` |
| 23 | + |
| 24 | +The package will automatically register itself. |
| 25 | + |
| 26 | +## Function List |
| 27 | + |
| 28 | +The `Laravel API Response Formatter` class provides the following functions: |
| 29 | + |
| 30 | +| Function | Description | |
| 31 | +| -------------------- | ----------------------------------------------------------------------------------------- | |
| 32 | +| `success()` | Formats a success response with optional data, message, status, and HTTP code. | |
| 33 | +| `created()` | Formats a created response with optional data, message, status, and HTTP code. | |
| 34 | +| `noContent()` | Formats a no content response with optional data, message, status, and HTTP code. | |
| 35 | +| `error()` | Formats an error response with optional data, message, status, and HTTP code. | |
| 36 | +| `unAuthenticated()` | Formats an unauthenticated response with optional data, message, status, and HTTP code. | |
| 37 | +| `forbidden()` | Formats a forbidden response with optional data, message, status, and HTTP code. | |
| 38 | +| `notFound()` | Formats a not found response with optional data, message, status, and HTTP code. | |
| 39 | +| `methodNotAllowed()` | Formats a method not allowed response with optional data, message, status, and HTTP code. | |
| 40 | +| `failedValidation()` | Formats a failed validation response with optional data, message, status, and HTTP code. | |
| 41 | + |
| 42 | +## Parameters |
| 43 | + |
| 44 | +The functions in the `Laravel API Response Formatter` class accept the following parameters: |
| 45 | + |
| 46 | +- `$data` (optional): The data to be included in the response. It can be of any type. |
| 47 | +- `$message` (optional): The message to be included in the response. If not provided, a default message will be used. |
| 48 | +- `$status` (optional): The success status of the response. Defaults to `true` for success responses and `false` for error responses. |
| 49 | +- `$httpCode` (optional): The HTTP response code to be returned. It defaults to the corresponding HTTP status code for each response type. |
| 50 | + |
| 51 | +## Example Usage |
| 52 | + |
| 53 | +Here's an example of how you can use the `Laravel API Response Formatter` class in a user controller: |
| 54 | + |
| 55 | +```php |
| 56 | +<?php |
| 57 | + |
| 58 | +use Okriiza\ApiResponseFormatter\ApiResponse; |
| 59 | + |
| 60 | +class UserController extends Controller |
| 61 | +{ |
| 62 | + public function show($id): JsonResponse |
| 63 | + { |
| 64 | + $user = User::find($id); |
| 65 | + |
| 66 | + if ($user) { |
| 67 | + return ApiResponse::success($user); |
| 68 | + } else { |
| 69 | + return ApiResponse::notFound(null, 'User not found'); |
| 70 | + } |
| 71 | + } |
| 72 | + |
| 73 | + public function create(Request $request): JsonResponse |
| 74 | + { |
| 75 | + // Validation logic |
| 76 | + |
| 77 | + if ($validationFails) { |
| 78 | + return ApiResponse::failedValidation($validationErrors); |
| 79 | + } |
| 80 | + |
| 81 | + $user = User::create($request->all()); |
| 82 | + |
| 83 | + return ApiResponse::created($user); |
| 84 | + } |
| 85 | +} |
| 86 | +``` |
| 87 | + |
| 88 | +In the above example, the `show()` method fetches a user by ID and returns a success response if the user exists. If the user is not found, it returns a not found response. The `create()` method performs validation and creates a new user. If the validation fails, it returns a failed validation response. Otherwise, it returns a created response with the created user. |
| 89 | + |
| 90 | +```json |
| 91 | +{ |
| 92 | + "meta": { |
| 93 | + "code": 200, |
| 94 | + "success": true, |
| 95 | + "message": "OK" |
| 96 | + }, |
| 97 | + "result": { |
| 98 | + "id": 1, |
| 99 | + "name": "John Doe", |
| 100 | + "email": "john@example.com" |
| 101 | + } |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +And for an error case: |
| 106 | + |
| 107 | +```json |
| 108 | +{ |
| 109 | + "meta": { |
| 110 | + "code": 404, |
| 111 | + "success": false, |
| 112 | + "message": "User not found" |
| 113 | + }, |
| 114 | + "result": null |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +The `meta` object contains information about the response, such as the response code, status, and message. The `result` object holds the actual response data. |
| 119 | + |
| 120 | +Note: The examples provided are simplified and may require modifications to fit your specific use case |
| 121 | + |
| 122 | +## Contributing |
| 123 | + |
| 124 | +Please see [CONTRIBUTING](CONTRIBUTING.md) for details. |
| 125 | + |
| 126 | +### Security |
| 127 | + |
| 128 | +If you discover any security related issues, please email okriizaa@gmail.com instead of using the issue tracker. |
| 129 | + |
| 130 | +## Credits |
| 131 | + |
| 132 | +This package was created by [Rendi Okriza](https://github.com/okriiza) |
| 133 | + |
| 134 | +- [All Contributors](../../contributors) |
| 135 | + |
| 136 | +## License |
| 137 | + |
| 138 | +The Laravel API Response Formatter package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). |
0 commit comments