README

Laravel API 响应

Laravel 和 Lumen API 响应转换器/格式化器。

要求

• PHP ^7.4 | ^8.0
• Laravel 7, 8, 9 或 10

安装

通过 Composer

$ composer require raditzfarhan/laravel-api-response

配置

Laravel 和 Lumen 的配置略有不同，因此以下是每个框架的说明。

Laravel

编辑 config/app.php 文件并添加以下行以注册服务提供程序

'providers' => [
    ...
    RaditzFarhan\ApiResponse\ApiResponseServiceProvider::class,
    ...
],

提示：如果您使用的是 Laravel 版本 5.5 或更高版本，您可以跳过此部分的设置，改为使用自动发现功能。

Lumen

编辑 bootstrap/app.php 文件并添加以下行以注册服务提供程序

...
$app->register(RaditzFarhan\ApiResponse\ApiResponseServiceProvider::class);
...

您还需要在 bootstrap/app.php 中启用 Facades

..
$app->withFacades(true, [
    RaditzFarhan\ApiResponse\Facades\ApiResponse::class => 'ApiResponse'
]);
...

用法

以下代码片段是示例用法

// Success response

// using service container
$response = app('ApiResponse')->success();

// using alias
$response = \ApiResponse::success();

// Failed response
$response = \ApiResponse::failed();

响应将返回一个 Illuminate\Http\Response 实例，就像调用 response() 辅助方法一样。

默认情况下，如果未设置，成功将使用 HTTP 200 状态码，失败将使用 HTTP 500 状态码。

典型响应内容如下

成功

{
    "status": true,
    "http_code": 200,
    "message": "Success."
}

失败

{
    "status": false,
    "http_code": 500,
    "message": "Failed."
}

通过链式调用更多方法添加/更改有效负载数据，如下所示

// Example #1
return ApiResponse::httpCode(201)->message('Created new record!')->data(['name' => 'Raditz Farhan', 'country' => 'MY'])->success();

// or can be shorten to
return ApiResponse::created(['name' => 'Raditz Farhan', 'country' => 'MY']);

// Example #2
return ApiResponse::httpCode(422)->message('Validation error!')->errors(['name' => ['Name field is required.']])->failed();

// or can be shorten to
return ApiResponse::validationError(['name' => ['Name field is required.']]);

上述调用将产生以下结果

示例 #1

{
    "status": true,
    "http_code": 201,
    "message": "Created new record!",
    "data": {
        "name": "Raditz Farhan",
        "country": "MY"
    }    
}

示例 #2

{
    "status": false,
    "http_code": 422,
    "message": "Validation error!",
    "errors": {
        "name": [
            "Name field is required."
        ]
    },
}

使用 collection 方法返回包含 meta 和 links 属性的分页结果

return ApiResponse::collection(App\Post::paginate());

将返回以下结果

{
  "status": true,
  "http_code": 200,
  "message": "Success.",
  "data": [
    {
      "id": 1,
      "title": "First post",
      "slug": "first-post",
      "content": "This is the first post",
      "sort_order": 1,
      "created_at": "2020-04-21T13:40:45.000000Z",
      "updated_at": "2020-04-21T13:40:45.000000Z"
    },
    ...
  ],
  "meta": {
    "currenct_page": 1,
    "last_page": 3,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 60,
    "has_more_pages": true
  },
  "links": {
    "first": "http://your-app-url?page=1",
    "last": "http://your-app-url?page=3",
    "prev": null,
    "next": "http://your-app-url?page=2"
  }
}

除了 created 和 validationError 之外，以下简写方法也适用于您的方便

// return http 400 Bad request error.
return ApiResponse::badRequest('Optional message here'); 

// return http 401 Unauthorized error.
return ApiResponse::unauthorized(); 

// return http 403 Forbidden error.
return ApiResponse::forbidden(); 

// return http 404 Not found error.
return ApiResponse::notFound(); 

// return http 500 Internal server error.
return ApiResponse::internalServerError(); 

提示：向方法传递消息以添加您自己的自定义消息。

变更日志

请参阅 变更日志 以获取有关最近更改的更多信息。

致谢

• Raditz Farhan

许可

MIT。请参阅 许可文件 以获取更多信息。