spatie/fractalistic

围绕 Fractal 的开发者友好型包装器

维护者

详情

github.com/spatie/fractalistic

主页

源代码

问题

资助包维护！
spatie

安装次数: 10,844,768

依赖者: 9

建议者: 6

安全: 0

星标: 382

关注者: 6

分支: 33

开放问题: 1

2.9.5 2022-04-21 12:26 UTC

Requires

Requires (Dev)

MIT 6f12686a03d035f4558d166989c62aa93bde2151

apitransformfractalspatiefractalistic

This package is auto-updated.

Last update: 2024-08-29 14:05:25 UTC

README

围绕 Fractal 的开发者友好型包装器

Latest Version on Packagist Software License GitHub Workflow Status Quality Score Total Downloads

Fractal 是一个用于在 API 中使用前转换数据的出色包。不幸的是，与 Fractal 一起工作可能有点冗长。

使用 Fractal 数据可以像这样进行转换

use League\Fractal\Manager;
use League\Fractal\Resource\Collection;

$books = [
   ['id'=>1, 'title'=>'Hogfather', 'characters' => [...]], 
   ['id'=>2, 'title'=>'Game Of Thrones', 'characters' => [...]]
];

$manager = new Manager();

$resource = new Collection($books, new BookTransformer());

$manager->parseIncludes('characters');

$manager->createData($resource)->toArray();

此包使此过程更加简单

Fractal::create()
   ->collection($books)
   ->transformWith(new BookTransformer())
   ->includeCharacters()
   ->toArray();

还有一个非常短的语法可供快速转换数据

Fractal::create($books, new BookTransformer())->toArray();

如果您想在 Laravel 中使用此包，建议您使用 laravel-fractal。该包包含一些专门针对 Laravel 用户的功能。

Spatie 是一家位于比利时安特卫普的网络设计公司。您可以在我们的网站上找到所有开源项目的概述 在此。

支持我们

我们投入了大量资源来创建 最佳开源包。您可以通过 购买我们的付费产品之一 来支持我们。

我们非常感谢您从您的家乡寄给我们明信片，说明您正在使用我们的哪个包。您可以在 我们的联系页面 上找到我们的地址。我们将在 我们的虚拟明信片墙上 发布收到的所有明信片。

安装

您可以通过 composer 拉取此包

composer require spatie/fractalistic

使用

在以下示例中，我们将使用以下数组作为示例输入

$books = [['id'=>1, 'title'=>'Hogfather'], ['id'=>2, 'title'=>'Game Of Kill Everyone']];

但请注意，任何可以循环的结构（例如集合）都可以使用。

让我们从一个简单的转换开始。

Spatie\Fractalistic\Fractal::create()
   ->collection($books)
   ->transformWith(function($book) { return ['id' => $book['id']];})
   ->toArray();

这将返回

['data' => [['id' => 1], ['id' => 2]]

在所有后续示例中，假设您已经在您的 php 文件顶部导入了 Spatie\Fractalistic\Fractal。

您还可以传递 转换器

Fractal::create()
   ->collection($books)
   ->transformWith(new BookTransformer())
   ->toArray();

您也可以传递转换器的类名

Fractal::create()
   ->collection($books)
   ->transformWith(BookTransformer::class)
   ->toArray();

为了使您的代码更短，您还可以将转换闭包、类或类名作为第二个参数传递给 collection-方法

Fractal::create()->collection($books, new BookTransformer())->toArray();

想要一些美味的 JSON 输出而不是数组？没问题！

Fractal::create()->collection($books, new BookTransformer())->toJson();

单个项目也可以进行转换

Fractal::create()->item($books[0], new BookTransformer())->toArray();

使用序列化器

让我们再次看看第一个示例的输出

['data' => [['id' => 1], ['id' => 2]];

注意那个 data 键？这是 Fractal 的默认行为的一部分。查看 Fractal 的序列化器文档 以了解为什么会发生这种情况。

如果您想使用其他序列化器，您可以使用 serializeWith-方法指定一个。默认情况下，Spatie\Fractalistic\ArraySerializer 包含在内部。它删除了集合和项目的 data 命名空间。

Fractal::create()
   ->collection($books)
   ->transformWith(function($book) { return ['id' => $book['id']];})
   ->serializeWith(new \Spatie\Fractalistic\ArraySerializer())
   ->toArray();

//returns [['id' => 1], ['id' => 2]]

您也可以传递序列化器的类名而不是实例化

Fractal::create()
   ->collection($books)
   ->transformWith(BookTransformer::class)
   ->serializeWith(MySerializer::class)
   ->toArray();

更改默认序列化器

您可以通过在配置文件中提供您最喜欢的序列化器的类名或实例来更改默认序列化器。

使用 includes

Fractal 为导出数据的关联数据提供了 可选包括数据 的支持。您可以使用 Fractal 的 parseIncludes，它接受一个字符串或一个数组

Fractal::create()
   ->collection($this->testBooks, new TestTransformer())
   ->parseIncludes(['characters', 'publisher'])
   ->toArray();

为了提高可读性，您还可以使用一个名为 include 的函数，后面跟您想要包含的包含名称...

Fractal::create()
   ->collection($this->testBooks, new TestTransformer())
   ->includeCharacters()
   ->includePublisher()
   ->toArray();

使用排除项

类似于包含，Fractal 也提供了对可选排除数据的支持，用于您导出的数据的关系。您可以使用 Fractal 的 parseExcludes，它接受一个字符串或一个数组

Fractal::create()
   ->collection($this->testBooks, new TestTransformer())
   ->parseExcludes(['characters', 'publisher'])
   ->toArray();

为了提高可读性，您还可以使用一个名为 exclude 的函数，后面跟您想要排除的包含名称...

Fractal::create()
   ->collection($this->testBooks, new TestTransformer())
   ->excludeCharacters()
   ->excludePublisher()
   ->toArray();

包含元数据

Fractal 支持包含元数据。您可以使用 addMeta，它接受一个或多个数组

Fractal::create()
   ->collection($this->testBooks, function($book) { return ['name' => $book['name']];})
   ->addMeta(['key1' => 'value1'], ['key2' => 'value2'])
   ->toArray();

这将返回以下数组

[
   'data' => [
        ['title' => 'Hogfather'],
        ['title' => 'Game Of Thrones'],
    ],
   'meta' => [
        ['key1' => 'value1'], 
        ['key2' => 'value2'],
    ]
];

使用分页

Fractal 提供了一个 Laravel 特定的分页器 IlluminatePaginatorAdapter，它接受 Laravel 的 LengthAwarePaginator 实例，并与分页的 Eloquent 结果一起工作。当使用某些序列化器，如 JsonApiSerializer 时，分页数据可以自动生成并包含在结果集中

$paginator = Book::paginate(5);
$books = $paginator->getCollection();

Fractal::create()
    ->collection($books, new TestTransformer())
    ->serializeWith(new JsonApiSerializer())
    ->paginateWith(new IlluminatePaginatorAdapter($paginator))
    ->toArray();

使用游标

Fractal 提供了一个简单的游标类 League\Fractal\Pagination\Cursor。只要它实现了 League\Fractal\Pagination\CursorInterface 接口，您就可以使用任何其他游标类。当使用它时，游标信息将自动包含在结果元数据中

$books = $paginator->getCollection();

$currentCursor = 0;
$previousCursor = null;
$count = count($books);
$newCursor = $currentCursor + $count;

Fractal::create()
  ->collection($books, new TestTransformer())
  ->serializeWith(new JsonApiSerializer())
  ->withCursor(new Cursor($currentCursor, $previousCursor, $newCursor, $count))
  ->toArray();

设置自定义资源名称

某些序列化器将数组输出包裹在一个 data 元素中。此元素的名称可以自定义

Fractal::create()
    ->collection($this->testBooks, new TestTransformer())
    ->serializeWith(new ArraySerializer())
    ->withResourceName('books')
    ->toArray();
Fractal::create()
    ->item($this->testBooks[0], new TestTransformer(), 'book')
    ->serializeWith(new ArraySerializer())
    ->toArray();

限制递归

要增加或减少嵌套包含的级别，您可以使用 limitRecursion。

Fractal::create()
    ->collection($this->testBooks, new TestTransformer())
    ->includesDataThatHasALotOfRecursion
    ->limitRecursion(5);

如果您没有调用 limitRecursion，则默认值使用 10。

使用简短函数语法快速转换数据

您还可以向 fractal 函数本身传递参数。第一个参数应该是您要转换的数据。第二个参数应该是用于转换数据的转换器或 closure。第三个参数应该是序列化器。

以下是一些示例

Fractal::create($books, new BookTransformer())->toArray();

Fractal::create($books, new BookTransformer(), new ArraySerializer())->toArray();

Fractal::create($books, BookTransformer::class, ArraySerializer::class)->toArray();

Fractal::create(['item1', 'item2'], function ($item) {
   return $item . '-transformed';
})->toArray();

更新日志

有关最近更改的更多信息，请参阅更新日志。

测试

$ composer test

贡献

有关详细信息，请参阅贡献指南。

安全

如果您发现有关安全性的错误，请通过[email protected] 发送电子邮件，而不是使用问题跟踪器。

明信片软件

您可以自由使用此包，但如果它进入了您的生产环境，我们非常感激您从家乡给我们寄一张明信片，说明您正在使用我们哪个包。

我们的地址是：Spatie，Kruikstraat 22，2018 安特卫普，比利时。

我们在我们的公司网站上发布所有收到的明信片。

致谢

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件。