README

Presentit 是一个易于使用的工具，用于自定义 API 响应中使用的嵌套数据结构的展示。

Present::item($user)->with(function (User $user) {
    return [
        'id' => $user->id,
        'name' => $user->first_name . " " . $user->last_name,
        'image' => $user->image ?: Present::hidden(),
        'friends' => Present::each($user->friends)->with(function (User $friend) {
            return [
                //...
            ]
        })
    ];
})->show();

特性

• 流畅的接口来转换嵌套数据结构
• 用于展示逻辑代码重用的转换器类。
• 用于内联数据转换的回调转换器。
• 使用 Hidden 对象而不是 if 语句来控制数据属性的可视性。

适配器

• Laravel 框架适配器

文档

• 安装
• 基本用法

安装

使用 composer 安装

composer require dan-har/presentit

基本用法

Present 类用于转换单个资源或资源集合。

使用 item() 方法展示单个资源。

$presentation = Present::item($user)->with(function (User $user) {
    return [
        'id' => $user->id,
        'first_name' => ucfirst($user->first_name),
        // ...
    ];
});

使用 collection 或 each 方法展示资源列表。列表中的每个项目都将使用传递给 each 方法的转换器进行转换。

$presentation = Present::collection($usersList)->with(function (User $user) {
    return [
        'id' => $user->id,
        'first_name' => ucfirst($user->first_name),
        // ...
    ];
});

with 函数接受一个转换器，并返回一个 Presentation 对象。要获取展示数据为数组，请使用 show 方法。

$array = $presentation->show();

通常与 HTTP 响应对象一起使用 Presentation。以下是与 Symphony JsonResponse 一起使用的示例。

$response = new JsonResponse($presentation->show());

$response->send();

使用 Hidden 对象隐藏键。

$presentation = Present::item($user)->with(function (User $user) {
    return [
        'id' => $user->id,
        'first_name' => ucfirst($user->first_name),
        'birthday' => $user->isBirthDayPublic() ? $user->birthday : Present::hidden() // or use Hidden::key()
        // ...
    ];
});

当数组数据结构中的值是 Hidden 类型时，该键将不会被展示。上面的示例展示将变为

$array = $presentation->show();

// if birthday is not public ->
// $array = [
//     'id' => $user->id,
//     'first_name' => ucfirst($user->first_name),
// ]
// birthday key is not visible.

with 方法接受一个转换器。转换器可以是 callable、Transformer 实例或转换器类 string 名称。

使用 Transformer 类 string

class UserTransformer 
{
    public function transform(User $user) 
    {
        return [
            'id' => $user->id,
            'first_name' => ucfirst($user->first_name),
            // ...
        ];
    } 
}

$presentation = Present::each($usersList)->with(UserTransformer::class);

或使用 Transformer 实例

$tranformer = new UserTransformer();

$presentation = Present::item($user)->with($transformer);
$presentation = Present::each($usersList)->with($transformer);

使用 Transformer 类的嵌套展示

use Presentit\Present;

class UserTransformer 
{
    public function transform(User $user) 
    {
        return [
            'id' => $user->id,
            'first_name' => ucfirst($user->first_name),
            'friends' => $user->friends ? Present::each($user->friends)->with(UserTransformer::class) : [],
            // ...
        ];
    } 
}

$presentation = Present::each($usersList)->with(UserTransformer::class);