README

该软件包为Laravel应用提供了对Fractal的一个优美且易于使用的封装。如果你不知道Fractal是做什么的，可以查看他们的简介。简而言之，Fractal在将数据用于API之前转换数据非常有用。

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

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

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

$manager = new Manager();

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

$manager->parseIncludes('characters');

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

此软件包使此过程更加简单

fractal()
   ->collection($books)
   ->transformWith(new BookTransformer())
   ->includeCharacters()
   ->toArray();

喜欢外观的人会很高兴知道提供了一个外观

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

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

fractal($books, new BookTransformer())->toArray();

您还可以直接从Laravel集合转换

collect($books)->transformWith(new BookTransformer());

直接从Laravel集合转换对于Eloquent结果特别有用

Users::all()->transformWith(new UserTransformer())->toArray();

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

Laravel 5.4中的安装

您可以通过composer引入此软件包

composer require spatie/laravel-fractal:^4.0

然后按照此软件包v4分支的安装说明进行操作。

Laravel 5.5及更高版本的安装

您可以通过composer引入此软件包

composer require spatie/laravel-fractal

软件包将自动注册自己。

如果您想更改默认序列化器、默认分页器或默认Fractal类Spatie\Fractal\Fractal，您必须发布配置文件

php artisan vendor:publish --provider="Spatie\Fractal\FractalServiceProvider"

如果您正在升级到Laravel 5.5，现有的配置文件应从laravel-fractal.php重命名为fractal.php

这是发布文件的内容

return [
     /*
     * The default serializer to be used when performing a transformation. It
     * may be left empty to use Fractal's default one. This can either be a
     * string or a League\Fractal\Serializer\SerializerAbstract subclass.
     */
    'default_serializer' => '',

    /* The default paginator to be used when performing a transformation. It
     * may be left empty to use Fractal's default one. This can either be a
     * string or a League\Fractal\Paginator\PaginatorInterface subclass.*/
    'default_paginator' => '',

    /*
     * League\Fractal\Serializer\JsonApiSerializer will use this value to
     * as a prefix for generated links. Set to `null` to disable this.
     */
    'base_url' => null,

    /*
     * If you wish to override or extend the default Spatie\Fractal\Fractal
     * instance provide the name of the class you want to use.
     */
    'fractal_class' => Spatie\Fractal\Fractal::class,

    'auto_includes' => [

        /*
         * If enabled Fractal will automatically add the includes who's
         * names are present in the `include` request parameter.
         */
        'enabled' => true,

        /*
         * The name of key in the request to where we should look for the includes to include.
         */
        'request_key' => 'include',
    ],

使用方法

有关本软件包提供的所有方法，请参阅spatie/fractalistic的文档。

在所有代码示例中，您可以使用fractal()代替Fractal::create()。

发送包含转换数据的响应

要返回包含JSON数据的响应，您可以在Laravel应用中这样做。

$books = fractal($books, new BookTransformer())->toArray();

return response()->json($books);

Fractal类上的respond()方法可以使此过程更加流畅。

return fractal($books, new BookTransformer())->respond();

您可以将响应代码作为第一个参数传递，并可选地传递一些作为第二个参数的标题

return fractal($books, new BookTransformer())->respond(403, [
    'a-header' => 'a value',
    'another-header' => 'another value',
]);

您可以将JSON编码选项作为第三个参数传递

return fractal($books, new BookTransformer())->respond(200, [], JSON_PRETTY_PRINT);

您还可以使用回调设置状态代码和标题

use Illuminate\Http\JsonResponse;

return fractal($books, new BookTransformer())->respond(function(JsonResponse $response) {
    $response
        ->setStatusCode(403)
        ->header('a-header', 'a value')
        ->withHeaders([
            'another-header' => 'another value',
            'yet-another-header' => 'yet another value',
        ]);
});

快速创建转换器

您可以使用make:transformer命令快速生成一个虚拟转换器。默认情况下，它将存储在app\Transformers目录中。

升级

从v4到v5

将您的配置文件从laravel-fractal重命名为fractal

从v2到v3

v3引入了用spatie/fractalistic替换league/fractal。对Lumen的支持已删除。您应该能够通过不进行任何代码更改来升级从v2到v3的Laravel应用程序。

从v1到v2

在大多数情况下，您可以直接升级到v2，而无需对您的代码进行任何或只有少量更改。

resourceName 已重命名为 withResourceName。

此包的 v2 版本被标记的主要原因是因为底层 League 的 Fractal 的 v0.14 版本包含破坏性变更。如果您在 v2 版本中使用 League\Fractal\Serializer\JsonApiSerializer，则 links 键将包含 self、first、next 和 last。

变更日志

请参阅 CHANGELOG 了解最近的变化信息。

测试

$ composer test

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全

如果您发现任何与安全相关的问题，请发送电子邮件至 freek@spatie.be，而不是使用问题跟踪器。

明信片软件

您可以使用此包，但如果它进入您的生产环境，我们非常欢迎您从家乡寄给我们一张明信片，提及您正在使用我们哪个包。

我们的地址是：Spatie，Samberstraat 69D，2060 安特卫普，比利时。

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

致谢

支持我们