Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jiannei/laravel-response
🤖 Provide a standardized and unified response data structure for Laravel and Lumen API projects. - 为 Laravel 和 Lumen API 项目提供一个规范统一的响应数据结构。
https://github.com/jiannei/laravel-response
laravel-response lumen-response response-formatter
Last synced: 3 days ago
JSON representation
🤖 Provide a standardized and unified response data structure for Laravel and Lumen API projects. - 为 Laravel 和 Lumen API 项目提供一个规范统一的响应数据结构。
- Host: GitHub
- URL: https://github.com/jiannei/laravel-response
- Owner: jiannei
- License: mit
- Created: 2020-11-29T14:29:25.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-12-17T08:12:58.000Z (14 days ago)
- Last Synced: 2024-12-21T09:01:00.156Z (10 days ago)
- Topics: laravel-response, lumen-response, response-formatter
- Language: PHP
- Homepage:
- Size: 202 KB
- Stars: 257
- Watchers: 3
- Forks: 34
- Open Issues: 1
-
Metadata Files:
- Readme: README-EN.md
- License: LICENSE
Awesome Lists containing this project
README
laravel-response
[简体中文](README.md) | [ENGLISH](README-EN.md)
> Provide a standardized and unified response data format for Laravel and Lumen API projects.
[](https://github.styleci.io/repos/316969462?style=flat&branch=main)
[](https://packagist.org/packages/jiannei/laravel-response)
[](https://packagist.org/packages/jiannei/laravel-response)
[](https://packagist.org/packages/jiannei/laravel-response)
[](https://packagist.org/packages/jiannei/laravel-response)
## Introduce
`laravel-response` It is mainly used to unify the response data format of "success", "failure" and "exception" in the process of API development.
It is encapsulated in the original `\Illuminate\Http\JsonResponse`, there is nothing complicated.
Follow certain specifications, return HTTP status codes that are easy to understand, and support the definition of 'enum' to meet the return of descriptive business operation codes in different scenarios.
## Features
- Unified data response format, including:`code`、`status`、`data`、`message`、`error`
- You can continue to chain call all public methods in the `JsonResponse` class, such as `Response::success()->header('x-foo ',' bar ')`
- Reasonably return the HTTP status code. The default is restful strict mode. You can configure to return 200 HTTP status code in case of exception (this is how most projects use it)
- It supports the formatting of `Api Resource`、`Api Resource Collection`、`Paginator`、`LengthAwarePaginator`、`Eloquent\Model`、`Eloquent\Collection`,as well as the return of data in simple formats such as `array` 和 `string`
- According to the debug config, reasonably return the exception information, verify the exception information
- It supports modifying the status code or prompt information of laravel's special exception, such as modifying the exception prompt of `No query results for model` to `data not found`
- Any returned field can be displayed or hidden, and aliases can be set, such as alia `message` to `msg`
- The formatted result of paging data is consistent with the format converted by the transformer using `league/fractal` (DingoApi uses this extension for data conversion), that is, it can be smoothly switched from laravel API resource to `league/fractal`
- Built in HTTP standard status code support, and support the extension of ResponseCodeEnum to define response codes according to different business modules (optional, need to install `jiannei/laravel-enum`)
## Install
Support for laravel 5.5. *~ Laravel 10.*, the user-defined business operation code partially depends on [jiannei/laravel-enum](https://github.com/Jiannei/laravel-enum).
| laravel version | lumen version | response version | enum version |
|------------| ---- |-------------| ---- |
| 5.5.* | 5.5.* | ~1.8 | ~1.4 |
| 6.* | 6.* | ^2.0 | ~1.4 |
| 7.* | 7.* | ^3.0 | ^2.0 |
| 8.* | 8.* | ^4.0 | ^3.0 |
| 9.* - 10.* | 9.* - 10.* | ^5.0 | ^3.0 |
```shell
# laravel 5.5
composer require jiannei/laravel-response "~1.8" -vvv
composer require jiannei/laravel-enum "~1.4" -vvv # optional
# laravel 6.x
composer require jiannei/laravel-response "^2.0" -vvv
composer require jiannei/laravel-enum "~1.4" -vvv # optional
# laravel 7.x
composer require jiannei/laravel-response "^3.0" -vvv
composer require jiannei/laravel-enum "^2.0" -vvv # optional
# laravel 8.x
composer require jiannei/laravel-response "^4.0" -vvv
composer require jiannei/laravel-enum "^3.0" -vvv # optional
# laravel 9.x - 10.x
composer require jiannei/laravel-response "^5.0" -vvv
composer require jiannei/laravel-enum "^3.0" -vvv # optional
```
## Configuration
### Laravel
- publish config file
```shell
$ php artisan vendor:publish --provider="Jiannei\Response\Laravel\Providers\LaravelServiceProvider"
```
- format exception response
```php
// app/Exceptions/Handler.php
// The exceptions generated by API requests will be formatted and returned
// The request header is required to contain /json or +json, such as Accept:application/json
// Or Ajax request, the header contains X-Requested-With：XMLHttpRequest;
configure('response');
```
- format exception response
In `app/Exceptions/Handler.php` file `use Jiannei\Response\Laravel\Support\Traits\ExceptionTrait;`
In `app/Http/Controllers/Controller.php` file `use Jiannei\Response\Laravel\Support\Traits\ExceptionTrait;`
- register service provider
```php
$app->register(\Jiannei\Response\Laravel\Providers\LumenServiceProvider::class);
```
## Usage
The extension package itself provides rich unit test cases,you can unlock usage by viewing test cases [tests](https://github.com/Jiannei/laravel-response/tree/main/tests)
Or view the corresponding template projects:
- [laravel-api-starter](https://github.com/Jiannei/laravel-api-starter)
- [lumen-api-starter](https://github.com/Jiannei/lumen-api-starter)
### Successful response
#### Sample code
```php
'Jiannel',
'email' => '[email protected]'
],'', ResponseCodeEnum::SERVICE_REGISTER_SUCCESS);
}
```
#### Return all rows data
Support custom inner `data` field names, such as `rows` or `list`
```json
{
"status": "success",
"code": 200,
"message": "操作成功",
"data": {
"data": [
{
"nickname": "Joaquin Ondricka",
"email": "[email protected]"
},
{
"nickname": "Jermain D'Amore",
"email": "[email protected]"
},
{
"nickname": "Erich Moore",
"email": "[email protected]"
}
]
},
"error": {}
}
```
#### Paginator
Support custom inner `data` field names, such as `rows` or `list`
```json
{
"status": "success",
"code": 200,
"message": "操作成功",
"data": {
"data": [
{
"nickname": "Joaquin Ondricka",
"email": "[email protected]"
},
{
"nickname": "Jermain D'Amore",
"email": "[email protected]"
},
{
"nickname": "Erich Moore",
"email": "[email protected]"
},
{
"nickname": "Eva Quitzon",
"email": "[email protected]"
},
{
"nickname": "Miss Gail Mitchell",
"email": "[email protected]"
}
],
"meta": {
"pagination": {
"count": 5,
"per_page": 5,
"current_page": 1,
"total": 12,
"total_pages": 3,
"links": {
"previous": null,
"next": "http://laravel-api.test/api/users/paginate?page=2"
}
}
}
},
"error": {}
}
```
#### Simple Paginator
Support custom inner `data` field names, such as `rows` or `list`
```json
{
"status": "success",
"code": 200,
"message": "操作成功",
"data": {
"data": [
{
"nickname": "Joaquin Ondricka",
"email": "[email protected]"
},
{
"nickname": "Jermain D'Amore",
"email": "[email protected]"
},
{
"nickname": "Erich Moore",
"email": "[email protected]"
},
{
"nickname": "Eva Quitzon",
"email": "[email protected]"
},
{
"nickname": "Miss Gail Mitchell",
"email": "[email protected]"
}
],
"meta": {
"pagination": {
"count": 5,
"per_page": 5,
"current_page": 1,
"links": {
"previous": null,
"next": "http://laravel-api.test/api/users/simple-paginate?page=2"
}
}
}
},
"error": {}
}
```
#### Return one row data
```json
{
"status": "success",
"code": 200,
"message": "操作成功",
"data": {
"nickname": "Joaquin Ondricka",
"email": "[email protected]"
},
"error": {}
}
```
#### Other shortcuts
```php
Response::ok();// There is no need to return data, but only message
Response::localize(200101);// There is no need to return data, return message according to the response code
Response::accepted();
Response::created();
Response::noContent();
```
### Failure response
#### Do not specify message
```php
public function fail()
{
Response::fail();// 不需要加 return
}
```
- localization is not configured
```json
{
"status": "fail",
"code": 500,
"message": "Http internal server error",
"data": {},
"error": {}
}
```
- localization is configured
```json
{
"status": "fail",
"code": 500,
"message": "操作失败",
"data": {},
"error": {}
}
```
#### Specify message
```php
public function fail()
{
Response::fail('error');// 不需要加 return
}
```
return response
```json
{
"status": "fail",
"code": 500,
"message": "error",
"data": {},
"error": {}
}
```
#### Specify code
```php
public function fail()
{
Response::fail('',ResponseCodeEnum::SERVICE_LOGIN_ERROR);
}
```
return response
```json
{
"status": "fail",
"code": 500102,
"message": "登录失败",
"data": {},
"error": {}
}
```
#### Other shortcuts
```php
Response::errorBadRequest();
Response::errorUnauthorized();
Response::errorForbidden();
Response::errorNotFound();
Response::errorMethodNotAllowed();
Response::errorInternal();
```
### Exception response
#### Form validation exception
```json
{
"status": "error",
"code": 422,
"message": "验证失败",
"data": {},
"error": {
"email": [
"The email field is required."
]
}
}
```
#### An exception is thrown outside the controller
You can throw an `HttpException` using the `abort` helper function
```php
abort(500102,'登录失败');
// return response
{
"status": "fail",
"code": 500102,
"message": "登录失败",
"data": {},
"error": {}
}
```
#### Other exceptions
enable debug mode(`APP_DEBUG=true`)
```json
{
"status": "error",
"code": 404,
"message": "Http not found",
"data": {},
"error": {
"message": "",
"exception": "Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException",
"file": "/home/vagrant/code/laravel-api-starter/vendor/laravel/framework/src/Illuminate/Routing/AbstractRouteCollection.php",
"line": 43,
"trace": [
{
"file": "/home/vagrant/code/laravel-api-starter/vendor/laravel/framework/src/Illuminate/Routing/RouteCollection.php",
"line": 162,
"function": "handleMatchedRoute",
"class": "Illuminate\\Routing\\AbstractRouteCollection",
"type": "->"
},
{
"file": "/home/vagrant/code/laravel-api-starter/vendor/laravel/framework/src/Illuminate/Routing/Router.php",
"line": 646,
"function": "match",
"class": "Illuminate\\Routing\\RouteCollection",
"type": "->"
}
]
}
}
```
disable debug mode(`APP_DEBUG=false`)
```json
{
"status": "error",
"code": 404,
"message": "Http not found",
"data": {},
"error": {}
}
```
### Custom business code
```php
[
// 成功
ResponseCodeEnum::HTTP_OK => '操作成功', // 自定义 HTTP 状态码返回消息
ResponseCodeEnum::HTTP_INTERNAL_SERVER_ERROR => '操作失败', // 自定义 HTTP 状态码返回消息
ResponseCodeEnum::HTTP_UNAUTHORIZED => '授权失败',
// 业务操作成功
ResponseCodeEnum::SERVICE_REGISTER_SUCCESS => '注册成功',
ResponseCodeEnum::SERVICE_LOGIN_SUCCESS => '登录成功',
// 客户端错误
ResponseCodeEnum::CLIENT_PARAMETER_ERROR => '参数错误',
ResponseCodeEnum::CLIENT_CREATED_ERROR => '数据已存在',
ResponseCodeEnum::CLIENT_DELETED_ERROR => '数据不存在',
ResponseCodeEnum::CLIENT_VALIDATION_ERROR => '表单验证错误',
// 服务端错误
ResponseCodeEnum::SYSTEM_ERROR => '服务器错误',
ResponseCodeEnum::SYSTEM_UNAVAILABLE => '服务器正在维护，暂不可用',
ResponseCodeEnum::SYSTEM_CACHE_CONFIG_ERROR => '缓存配置错误',
ResponseCodeEnum::SYSTEM_CACHE_MISSED_ERROR => '缓存未命中',
ResponseCodeEnum::SYSTEM_CONFIG_ERROR => '系统配置错误',
// 业务操作失败：授权业务
ResponseCodeEnum::SERVICE_REGISTER_ERROR => '注册失败',
ResponseCodeEnum::SERVICE_LOGIN_ERROR => '登录失败',
],
];
```
## Project supported by JetBrains
Many thanks to Jetbrains for kindly providing a license for me to work on this and other open-source projects.
[](https://www.jetbrains.com/?from=https://github.com/jiannei)
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
## Stargazers over time
[](https://starchart.cc/jiannei/laravel-response)
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.
