README

简单的Laravel API响应包装器。

安装

1. 通过composer安装包

   $ composer require obiefy/api-response

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

   Obiefy\API\ApiResponseServiceProvider::class

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

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

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

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

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

基本用法

有几种方式可以使用该包：使用外观或使用辅助函数。无论哪种方式，您都将获得相同的结果，完全取决于您。

外观

use API;

...

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

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

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

辅助函数

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

例如，在下面的示例中，我们通过外观调用response()方法，并传递以下参数：将200作为状态码，将用户列表作为消息，将$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()辅助函数，并传递以下参数：将200作为状态码，将用户列表作为消息，将$users（用户集合）作为数据，将$code作为键值数组，以及将$error作为另一个键值数组。

public function index()
{
    $users = User::latest()->take(5)->get();
    $code = ['code' => 30566];
    $error = ['error' => '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()方法和直接将参数传递给辅助函数。再次强调，如何更好地使用它完全取决于您。

请查看以下代码示例。

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", ...}
    ]
}

辅助函数

该包提供了一组函数，可以帮助您加快开发过程。例如，您可以直接调用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（Pull Request），我们将非常高兴。

许可证

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