README

此包提供了一个简单的方法来创建展示器，可以用来装饰 Eloquent 模型。它受到了Hemp Presenter和Laravel API Resources的很大启发，但也有一些关键的不同之处

这是一个简化版，不提供特质和宏
它提供了一个简单的方法来处理分页模型
它不仅仅关注 JSON API 响应，而是一个通用目的装饰器，可以在项目的任何地方使用

TL;DR

装饰器是一个对象，它包装另一个对象以便向包装的对象添加功能。它还将调用传递给装饰器的类中不可用的方法的调用委托给被装饰的类。装饰器在您需要修改类功能而不依赖于继承时非常有用。您可以使用它向对象添加可选功能，如日志记录、访问控制等。一个展示器是一种装饰器，用于向应用程序的视图（如 Blade 视图或 API 响应）展示对象。

安装

通过Composer

$ composer require culturegr/presenter

在 Laravel 5.5+ 中，包的服务提供者应该自动发现，因此您不需要注册它。如果您出于某种原因需要手动注册，可以通过将其添加到 config/app.php 中的提供者数组来完成此操作。

'providers' => [
    // ...
    CultureGr\Presenter\PresenterServiceProvider::class,
],

使用

创建展示器类

可以通过运行 make:presenter Artisan 命令生成展示器类

php artisan make:presenter UserPresenter

这将生成一个空的 Presenter 类，位于 app/Presenters 中

自定义展示器类

展示器是简单的类，旨在封装复杂或重复的视图逻辑。例如，这是一个简单的 UserPresenter 类

<?php

namespace App\Presenters;

use CultureGr\Presenter\Presenter;

class UserPresenter extends Presenter
{

    public function fullname()
    {
        return $this->firstname.' '.$this->lastname;
    }
}

请注意，可以通过使用 $this 变量直接访问原始模型属性（如 firstname、lastname）。这是因为 Presenter 类会自动将属性和方法访问代理到底层模型。

该类有一个自定义方法 fullname，可以在使用此展示器实例的任何地方调用。

$presentedUser->firstname; //=> 'John'
$presentedUser->lastname; //=> 'Doe'
$presentedUser->fullname() //=> 'John Doe'

如果展示的模型需要转换为 JSON 结构，展示器类应定义一个 toArray 方法，该方法返回应转换为 JSON 的属性数组，以便在发送响应时使用。

<?php

namespace App\Presenters;

use CultureGr\Presenter\Presenter;

class UserPresenter extends Presenter
{
    public function fullname()
    {
        return $this->firstname.' '.$this->lastname;
    }

    public function toArray()
    {
        return [
            'id' => $this->id,
            'fullname' => $this->fullname()
             // ...                  
        ];
    }
}

展示单个模型

定义展示器后，可以使用 make 工厂方法创建展示模型

$user = User::first();
$presentedUser = UserPresenter::make($user);

展示模型可以在项目的任何地方使用。如果需要将模型序列化为响应（如视图或 API 响应），必须显式调用覆盖的 toArray 方法，或者可以直接从路由或控制器返回它。

<?php

namespace App\Http\Controllers;

use App\Models\User;
use App\Presenters\UserPresenter;

class UserController extends Controller
{
    public function show($id)
    {
        return view('users.show', [
            'user' => UserPresenter::make(User::find($id))->toArray()
        ]);
    }
}

展示集合

要展示一组模型，可以使用展示器类上的静态 collection 方法

$users = User::all();
$presentedUsers = UserPresenter::collection($users);

展示的模型集合可以在项目的任何地方使用。如果需要将集合序列化为响应（如视图或 API 响应），必须显式调用覆盖的 toArray 方法，或者可以直接从路由或控制器返回它。

<?php

namespace App\Http\Controllers;

use App\Models\User;
use App\Presenters\UserPresenter;

class UserController extends Controller
{
    public function index()
    {
        $users = User::all();

        return UserPresenter::collection($users);
    }
}

输出将类似于这样

[
    {"id": "1", "fullname": "John Doe"},
    {"id": "2", "fullname": "Jane Doe"}
]

展示分页集合

要展示模型的分页集合，可以使用表示器类上的静态 pagination 方法

$users = User::paginate();
$presentedUsers = UserPresenter::pagination($users);

展示的模型分页集合可以在项目的任何地方使用。如果需要将集合序列化到响应中（如视图或API响应），必须显式调用覆盖的 toArray 方法，或者可以直接从路由或控制器返回

<?php

namespace App\Http\Controllers;

use App\Models\User;
use App\Presenters\UserPresenter;

class UserController extends Controller
{
    public function index()
    {
        $users = User::paginate();

        return UserPresenter::pagination($users);
    }
}

输出将包含在 data 键中的展示模型，同时包含有关分页器状态的 meta 和 links 键的信息

{
    "data": [
        {"id": "1", "fullname": "John Doe"},
        {"id": "2", "fullname": "Jane Doe"}
    ],
    "links":{
        "first": "http://example.com/pagination?page=1",
        "last": "http://example.com/pagination?page=1",
        "prev": null,
        "next": null
    },
    "meta":{
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://example.com/pagination",
        "per_page": 15,
        "to": 10,
        "total": 10
    }
}

测试

$ composer test

许可证

有关更多信息，请参阅许可证文件

鸣谢

向David Hemphill致以崇高的敬意
出色的Laravel/PHP社区

文化集团 / presenter

维护者

详细信息