README

简单的Laravel API响应包装器。

安装

1. 通过composer安装包

   $ composer require masudrana/api-response

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

   MasudRana\API\ApiResponseServiceProvider::class

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

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

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

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

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

基本用法

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

外观

use API;

...

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

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

注意：如果您决定不注册服务提供者和外观别名，那么您需要在类的顶部包含 use MasudRana\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，将消息设置为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()辅助函数并传递以下参数：将状态码设置为200，将消息设置为User list，将数据设置为$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许可下发布的免费软件包。