README

简单的Laravel API响应包装器。

安装

1. 通过composer安装包

   $ composer require obiefy/api-response

2. 在app.php文件中将包的服务提供者注册到提供者数组中

   Obiefy\API\ApiResponseServiceProvider::class

3. 在app.php文件中将包的facade别名注册到别名数组中

   'API' => Obiefy\API\Facades\API::class,

4. 最后，你可以发布配置文件

   php artisan vendor:publish --tag=api-response

注意：您也可以在类的顶部包含"use Obiefy\API\Facades\API;"，但我们建议不要这样做。

基本用法

使用该包有两种方式：使用facade或使用helper函数。无论哪种方式，您都会得到相同的结果，完全取决于您。

facade

use API;

...

public function index()
{
    $users = User::latest()->take(5)->get();

    return API::response(200, 'Latest 5 Users', $users);
}

注意：如果您决定不注册服务提供者和facade别名，您需要在类的顶部包含use Obiefy\API\Facades\API;，但我们建议不要这样做。

helper函数

public function index()
{
    $users = User::latest()->take(5)->get();

    return api()->response(200, 'Latest 5 Users', $users);
}

高级用法

response()方法接受三个必填参数

• int $status
• string $message
• string | array $data

例如，在下面的示例中，我们通过facade调用response()方法，并传递以下参数：将200作为状态码，将User list作为消息，将$users（用户集合）作为数据。

use API;

...

public function index()
{
    $users = User::latest()->take(5)->get();

    return API::response(200, 'Latest 5 Users', $users);
}

这是结果

{
    "STATUS": 200,
    "MESSAGE": "Latest 5 Users",
    "DATA": [
        {"name": "Obay Adam", ...}
    ]
}

如果您需要在json响应中除了默认的STATUS、MESSAGE和DATA属性之外还需要更多数据，您可以在$data之后传递任意多的参数。但是，我们建议将额外的参数格式化为$key => $value数组。

如以下示例所示，我们调用api() helper并传递以下参数：将200作为状态码，将User list作为消息，将$users（用户集合）作为数据，将$code作为键值数组，将$error作为另一个键值数组。

public function index()
{
    $users = User::latest()->take(5)->get();
    $code = ['code' => 30566];
    $error = ['reference' => 'ERROR-2019-09-14'];

    return api()->response(200, 'Latest 5 Users', $users, $code, $error);
}

这是结果

{
    "STATUS": 200,
    "MESSAGE": "Latest 5 Users",
    "DATA": [
        {"name": "Obay Adam", ...}
    ],
    "code": 30566,
    "error": "ERROR-2019-09-14"
}

创建响应的另一种方式是通过调用api()方法并直接将参数传递给helper函数。同样，如何更好地使用它完全取决于您。

请查看以下代码示例。

public function index()
{
    $users = User::latest()->take(5)->get();

    return api(200, 'Latest 5 Users', $users);
}

这是结果

{
    "STATUS": 200,
    "MESSAGE": "Latest 5 Users",
    "DATA": [
        {"name": "Obay Adam", ...}
    ]
}

helper函数

该包附带了一组函数，可以帮助您加快开发过程。例如，如果响应成功，您可以直接调用api()->ok()，而不是构建响应。

function ok()

ok()函数可以在不传递任何参数的情况下使用，它将默认状态码为200并使用配置文件中的默认消息。

return api()->ok();

结果

{
    "STATUS": 200,
    "MESSAGE": "Process is successfully completed",
    "DATA": {}
}

或者，您可以将自定义消息和所需数据传递给函数。在这种情况下，如之前所述，ok()状态码将默认为200。

$users = User::latest()->take(5)->get();

return api()->ok("User list", $users);

结果

{
    "STATUS": 200,
    "MESSAGE": "User list",
    "DATA": [
        {"name": "Obay Adam", ...}
    ]
}

function notFound()

如其名称所示，notFound()函数应在资源未找到时使用，状态码将默认为404。您可以向此函数传递自定义消息，否则它将使用配置文件中的默认消息。

return api()->notFound();

function validation()

在存在验证错误的情况下，可以使用 validation() 函数，默认抛出 422 状态码。它接受两个必填参数：一个信息和错误数组，以及您需要的任何额外参数（我们建议使用键值对数组格式）。如果信息为空，则将使用默认信息。

return api()->validation('These fields are required.', ['name', 'lastName']);

function error()

当发生内部服务器错误时，可以使用 error() 函数，默认抛出 500 状态码。它接受两个必填参数：一个信息和错误数组，以及您需要的任何额外参数（我们建议使用键值对数组格式）。如果信息为空，则将使用默认信息。

配置

JSON 响应标签

如果您需要自定义默认信息或 JSON 响应标签，可以直接在 api.php 配置文件中进行操作。

匹配状态码

默认情况下，所有 API 响应都会返回一个 200 OK HTTP 状态头。如果您想状态头与响应的状态相匹配，请将 matchstatus 配置设置为 true

包含数据数量

您可以在 api.php 配置文件中将 includeDataCount 设置为 true，以可选地包含响应 DATA 部分的数量。您还可以通过更新配置文件的 keys 数组中的标签来覆盖标签（如果需要的话）。

{
    "STATUS": "200",
    "MESSAGE": "User Profile data",
    "DATA": [
        ...
    ],
    "DATACOUNT": 6
}

贡献

如果您能向我们提供 PR，我们将非常高兴。

许可

API 响应是一个免费软件包，在 MIT 许可证下发布。