README

PHP 数据准备和展示包。

为什么选择 Presento？

Presento 是一个简单但强大的数据准备和展示工具。当我们构建基于 API 的应用程序时，我们需要在通过响应展示数据之前对数据进行转换。这个包将使这项任务更容易完成。

还不够清楚吗？

别担心，您可以从使用示例中获得更好的理解。

要求

PHP >= 7.0
ext-json

安装

使用 composer 安装此包

composer require nahid/presento

使用方法

Presento 具有两个重要功能：一个是展示，另一个是数据的转换。

让我们通过一些示例来了解如何使用它。

我们将使用以下数据集来展示示例。假设我们从某些数据源获取了此数据集，需要在发送到响应之前对其进行一些转换或修改。

$response = [
    "id" => 123456,
    "name" => "Nahid Bin Azhar",
    "email" => "talk@nahid.im",
    "type" => 1,
    "is_active" => 1,
    "created_at" => "2018-01-02 02:03:04",
    "updated_at" => "2018-01-02 02:03:04",
    "deleted_at" => "2018-01-02 02:03:04",
    "projects" => [
        [
            "id" => 1,
            "name" => "Laravel Talk",
            "url"   => "https://github.com/nahid/talk",
            "license" => "CC0",
            "created_at" => "2016-02-02 02:03:04"
        ],
        [
            "id" => 2,
            "name" => "JsonQ",
            "url"   => "https://github.com/nahid/jsonq",
            "license" => "MIT",
            "created_at" => "2018-01-02 02:03:04"
        ]
    ]
];

简单展示示例

当我们将此数据发送到 API 响应时，我们只想发送 id、name、email、type、is_active 和 projects。

我们可以简单地为此准备一个展示器，如下所示。

// UserPresenter.php

class UserPresenter extends \Nahid\Presento\Presenter
{
    public function present() : array
    {
        return [
            'id',
            'name',
            'email',
            'type',
            'is_active',
            'projects',
        ];
    }
}

你可能已经猜到了如何使用它，对吧？

$user = new UserPresenter($response);
dump($user->get());

它将显示如下内容

[
    "id" => 123456,
    "name" => "Nahid Bin Azhar",
    "email" => "talk@nahid.im",
    "type" => 1,
    "is_active" => 1,
    "projects" => [
        [
            "id" => 1,
            "name" => "Laravel Talk",
            "url"   => "https://github.com/nahid/talk",
            "license" => "CC0",
            "created_at" => "2016-02-02 02:03:04"
        ],
        [
            "id" => 2,
            "name" => "JsonQ",
            "url"   => "https://github.com/nahid/jsonq",
            "license" => "MIT",
            "created_at" => "2018-01-02 02:03:04"
        ]
    ]
]

很简单，对吧？

展示示例中的 'key' 别名

假设您想将某些 'key' 改为不同的名称，比如将 id 键更改为 user_id。您该如何操作？

只需这样做。

// UserPresenter.php
class UserPresenter extends \Nahid\Presento\Presenter
{
    public function present() : array
    {
        return [
            'user_id' => 'id',
            'name',
            'email',
            'type',
            'is_active',
        ];
    }
}

这将按以下格式格式化数据

[
    "user_id" => 123456,
    "name" => "Nahid Bin Azhar",
    "email" => "talk@nahid.im",
    "type" => 1,
    "is_active" => 1,
]

展示示例中的深度遍历

您可以使用 .（点）符号轻松地深入并获取嵌套级别中的数据。

假设您想显示数据中的第一个包的 name 作为 top_package。

您可以这样做。

// UserPresenter.php
class UserPresenter extends \Nahid\Presento\Presenter
{
    public function present() : array
    {
        return [
            'id',
            'name',
            'email',
            'type',
            'is_active',
            'top_package' => 'projects.0.name',
            'projects',
        ];
    }
}

这将按以下格式格式化数据

[
    "id" => 123456,
    "name" => "Nahid Bin Azhar",
    "email" => "talk@nahid.im",
    "type" => 1,
    "is_active" => 1,
    "top_package" => "Laravel Talk",
    "projects" => [
        [
            "id" => 1,
            "name" => "Laravel Talk",
            "url"   => "https://github.com/nahid/talk",
            "license" => "CC0",
            "created_at" => "2016-02-02 02:03:04"
        ],
        [
            "id" => 2,
            "name" => "JsonQ",
            "url"   => "https://github.com/nahid/jsonq",
            "license" => "MIT",
            "created_at" => "2018-01-02 02:03:04"
        ]
    ]
]

请注意数据中的 top_package 键。

简单转换示例

假设我们的 UserPresenter 如下所示

// UserPresenter.php
class UserPresenter extends \Nahid\Presento\Presenter
{
    public function present() : array
    {
        return [
            'user_id' => 'id',
            'name',
            'email',
            'type',
            'is_active',
        ];
    }
}

我们想以 哈希值 的形式显示 user_id，而不是数据库中的增量整数值。这意味着我们想转换 user_id。

为了做到这一点，我们需要创建一个转换类，如下所示

// UserTransformer.php
class UserTransformer extends \Nahid\Presento\Transformer
{
    public function getUserIdProperty($value)
    {
        return md5($value);
    }
}

请注意，由于我们将转换 user_id 属性，因此我们将转换器方法命名为 getUserIdProperty。因此，如果您还想转换 name 属性，您只需要在这个类中创建另一个名为 getNameProperty 的方法，并在其中添加转换逻辑。

现在，我们需要让 展示器 知道在展示之前如何转换数据。

为了做到这一点，我们需要在 UserPresenter 类中添加以下方法。

// UserPresenter.php
public function transformer()
{
    return UserTransformer::class;
}

因此，我们的最终输出将是

[
    "user_id" => "e10adc3949ba59abbe56e057f20f883e",
    "name" => "Nahid Bin Azhar",
    "email" => "talk@nahid.im",
    "type" => 1,
    "is_active" => 1,
]

很简单，对吧，伙计？

嵌套展示示例

您可能会注意到我们的数据集中有一个 projects 集合。如果每个 project 是一个单独的资源，您可能有一个用于该资源的单独展示器。如下所示

// ProjectPresenter.php
class ProjectPresenter extends \Nahid\Presento\Presenter
{
    public function present() : array
    {
        return [
            'id',
            'name',
            'url',
            'license',
            'created_at',
        ];
    }

    public function transformer()
    {
        return ProjectTransformer::class;
    }
}

您可以使用这个展示器来处理用户数据中的每个 projects 吗？

当然可以！只需这样做

// UserPresenter.php
public function present() : array
{
    return [
        'user_id' => 'id',
        'name',
        'email',
        'type',
        'is_active',
        'projects' => [ProjectPresenter::class => ['projects']],
    ];
}

现在，在用户中projects列表中的每个project都将按照ProjectPresenter中定义的方式呈现。

基础数据格式转换示例

正如您所看到的，我们至今使用的数据集是一个简单的数组。但有时可能并非如此。您可能需要处理不同的数据，比如Laravel框架中的Eloquent Model。在这种情况下，您可以在您的Presenter中简单地添加一个名为convert的方法，将基础数据转换为数组格式。

让我们看看一个示例

// UserPresenter.php
public function convert($data)
{
    if ($data instanceof Model) {
        return $data->toArray();
    }

    return $data;
}

就是这样。

nahid / presento

维护者

详细信息