README

简单的Laravel API响应包装器。

安装

1. 通过composer安装包

   $ composer require mdhesari/api-response

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

   Obiefy\API\ApiResponseServiceProvider::class

3. 将包的门面别名注册到app.php文件中的aliases数组

   '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::all();

    return API::response(200, 'users list', $users);
}

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

辅助函数

public function index()
{
    $users = User::all();

    return api()->response(200, 'users list', $users);
}

高级用法

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

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

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

use API;

...

public function index()
{
    $users = User::all();

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

这是结果

{
    "STATUS": 200,
    "MESSAGE": "Users list",
    "DATA": [
        {"name": "Obay Hamed"}
    ]
}

如果你需要在默认的STATUS、MESSAGE和DATA属性之外在你的JSON响应中包含更多数据，你可以在$data之后传递尽可能多的参数。然而，我们建议将额外的参数格式化为$key => $value数组。

正如你在下面的示例中看到的，我们通过调用api()辅助函数并传递以下参数：状态码为200，消息为User list，数据为$users（用户集合），键值数组为$code和另一个键值数组为$error。

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

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

这是结果

{
    "STATUS": 200,
    "MESSAGE": "Users list",
    "DATA": [
        {"name": "Obay Hamed"}
    ],
    "code": 30566,
    "error": "ERROR-2019-09-14"
}

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

查看以下代码示例。

public function index()
{
    $users = User::all();

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

这是结果

{
    "STATUS": 200,
    "MESSAGE": "users list",
    "DATA": [
        {"name": "Obay Hamed"}
    ]
}

辅助函数

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

function ok()

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

return api()->ok();

结果

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

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

$users = User::all();

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

结果

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

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 许可下发布。