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.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',
    ],
    
    'auto_excludes' => [

        /*
         * If enabled Fractal will automatically add the excludes 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 excludes to exclude.
         */
        'request_key' => 'exclude',
    ],

使用方法

请参阅 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->addMeta(['stats' => $stats]);
});

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

快速创建转换器

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

升级

从v4升级到v5

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

从v2升级到v3

v3引入了用spatie/fractalistic替换league/fractal。Lumen的支持已被取消。您应该能够在不修改任何代码的情况下将Laravel应用程序从v2升级到v3。

从v1升级到v2

在大多数情况下，您只需对代码进行少量或根本不进行修改即可升级到v2。

• resourceName已重命名为withResourceName。

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

更新日志

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

测试

$ composer test

贡献

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

安全性

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

鸣谢

• Freek Van der Herten
• 所有贡献者

许可

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