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();

喜欢门面（facade）的人会很高兴地知道，已经提供了一个门面

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 kunytskyi/laravel-fractal:^4.0

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

Laravel 5.5 及以上版本中的安装

您可以通过 composer 引入此包

composer require kunytskyi/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',
        ]);
});

您还可以使用 Laravel 的 Macroable 特性向 Fractal 类添加方法。假设您想在请求的元数据中添加一些统计信息，您可以在不使代码杂乱的情况下这样做

use Spatie\Fractal\Fractal;

Fractal::macro('stats', function ($stats) {
    // transform the passed stats as necessary here
    return $this->appendMeta(['stats' => $stats]);
});

fractal($books, new BookTransformer())->stats(['runtime' => 100])->respond();

快速创建转换器

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

升级

从v4升级到v5

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

从v2升级到v3

v3被引入以替换league/fractal为spatie/fractalistic。Lumen的支持已被移除。您应该能够在不进行任何代码更改的情况下将Laravel应用程序从v2升级到v3。

从v1升级到v2

在大多数情况下，您只需进行一些或不进行任何修改即可升级到v2。

resourceName已被重命名为withResourceName。

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

变更日志

有关最近更改的更多信息，请参阅CHANGELOG。

测试

$ composer test

贡献

有关详细信息，请参阅CONTRIBUTING。

安全

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

Postcardware

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

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

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

致谢

支持我们