README

Laravel/PHP 的域名负载实现

免责声明

PerfectOblivion 命名空间下的包旨在提供一些基本的函数，这些函数我不希望在每个项目中从头开始实现。这里没有什么突破性的东西。

负载包提供了一种简单的域名负载对象，可以封装来自控制器、服务类等的结果，以便可以轻松传递到响应中。

安装

您可以通过 composer 安装此包

composer require perfect-oblivion/payload

Laravel 版本 > 5.6.0 将自动识别并注册服务提供程序。如果您已禁用此功能，请将包服务提供程序添加到您的 config/app.php 文件中的 'providers' 数组中

'providers' => [
    //...
    PerfectOblivion\Payload\PayloadServiceProvider::class,
    //...
];

使用

目前，该包提供 Payload 类和一些 Laravel ResponseFactory 宏，以帮助将 Payload 转换为 JSON 响应或返回带有负载数据的视图。对于不使用 Laravel 的用户，有一些方法可以轻松检索负载数据以便进一步使用。

以下示例演示了在控制器类内部使用 Payload。`all()` 方法返回 Payload 输出、消息和状态作为数组，以便可以轻松访问并按需使用。

public function index(Request $request)
{
    $users = \App\Models\User::get();

    $payload = Payload::instance()
                    ->setOutput($users)
                    ->setMessages(['success' => 'Operation successful!'])
                    ->setStatus($payload::STATUS_OK);

    return $payload->all();
    // [
    //     'output' => [
    //         [
    //             'id' => 1,
    //             'name' => 'John Doe'
    //         ],
    //         [
    //             'id' => 2,
    //             'name' => 'Jane Doe'
    //         ],
    //         [
    //             'id' => 3,
    //             'name' => 'Sally Johnson'
    //         ]
    //     ],
    //     'messages' => [
    //         'success' => 'Operation successful!'
    //     ],
    //     'status' => 200
    // ]
}

消息和状态是可选的。您可以根据需要使用这些值返回响应。

使用 `all()` 方法，如果提供的输出可以自动转换为数组，则将进行转换。例如，在 Laravel 中，您可以将用户模型集合传递给 `setOutput()`。在这种情况下，`all()` 方法将用户对象集合转换为数组数组。要检索传递给 `setOutput()` 的原始数据，请调用 `getRawOutput()` 方法。

以下方法可用于从 Payload 对象检索信息

    /**
     * Get the status of the payload.
     */
    public function getStatus(): int;

    /**
     * Get messages array from the payload.
     */
    public function getMessages(): array;

    /**
     * Get the Payload output.
     */
    public function getOutput(): array;

    /**
     * Get the raw Payload output.
     *
     * @return mixed
     */
    public function getRawOutput();

    /**
     * Get the wrapped Payload output.
     */
    public function getWrappedOutput(): array;

    /**
     * Get the wrapper for the output.
     */
    public function getOutputWrapper(): string;

    /**
     * Get the wrapper for messages.
     */
    public function getMessagesWrapper(): string;

    /**
     * Return all of the components of the payload in array format.
     */
    public function all(): array;

响应辅助工具 / Laravel

如果您正在使用 Laravel，则有一些 ResponseFactory 宏可供您使用，这使得发送负载响应更加容易。

例如

$payload->setOutput($users, 'users')->setMessages(['success' => 'Operation Successful!']);
response()->jsonWithPayload($payload);

将产生以下结构

{
    "users": [
        {
            "id": 1,
            "name": "Clayton Stone",
            "email": "clay@test.com",
            "email_verified_at": "2019-03-18 20:29:26",
            "created_at": "2019-03-18 20:29:26",
            "updated_at": "2019-03-18 20:29:26"
        },
        {
            "id": 2,
            "name": "John Doe",
            "email": "john15@gmail.com",
            "email_verified_at": "2019-03-23 18:20:11",
            "created_at": "2019-03-23 18:19:41",
            "updated_at": "2019-03-23 18:20:16"
        }
    ],
    "messages": {
        "success": "Operation successful!"
    }
}

注意：使用这些辅助工具时，负载的状态代码也将随响应一起发送。

另一个辅助工具是 `viewWithPayload()`

response()->viewWithPayload('dashboard', $payload, 'payload');

`viewWithPayload()` 的第三个参数是您将用于在视图中引用数据的字符串。默认情况下，使用 'payload'。使用以下

$payload->setOutput($users, 'users')->setMessages(['success' => 'Operation Successful!']);
return response()->viewWithPayload('dashboard', $payload);

您将按以下方式访问您的数据

<h1>{{ $payload->name }}</h1>
<span>{{ $payload->email }}</span>

但是，您可以按以下方式设置第三个参数

$payload->setOutput($users, 'users')->setMessages(['success' => 'Operation Successful!']);
return response()->viewWithPayload('dashboard', $payload, 'user');

然后按以下方式访问您的数据

<h1>{{ $user->name }}</h1>
<span>{{ $user->email }}</span>

测试

composer test

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG

贡献

请参阅贡献文档以获取详细信息。

安全

如果您发现任何与安全相关的问题，请通过电子邮件clay@phpstage.com联系，而不是使用问题跟踪器。

路线图

我们计划很快开始工作于灵活性和配置，同时发布一个与框架无关的包版本。

鸣谢

许可协议

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

perfect-oblivion / payload

维护者

详细信息