Eloquent：API 资源

简介
生成资源
概念概述
- 资源集合
编写资源
资源响应

简介

当构建 API 时，您可能需要一个转换层，该层位于您的 Eloquent 模型和实际返回给应用程序用户的 JSON 响应之间。例如，您可能希望为一部分用户显示某些属性，而不为其他用户显示，或者您可能希望始终在模型的 JSON 表示中包含某些关系。Eloquent 的资源类允许您富有表现力且轻松地将模型和模型集合转换为 JSON。

当然，您始终可以使用 Eloquent 模型或集合的 toJson 方法将它们转换为 JSON；但是，Eloquent 资源提供了对模型及其关系的 JSON 序列化更精细和更强大的控制。

生成资源

要生成资源类，您可以使用 make:resource Artisan 命令。默认情况下，资源将放置在应用程序的 app/Http/Resources 目录中。资源扩展了 Illuminate\Http\Resources\Json\JsonResource 类

1php artisan make:resource UserResource

php artisan make:resource UserResource

资源集合

除了生成转换单个模型的资源之外，您还可以生成负责转换模型集合的资源。这允许您的 JSON 响应包含链接和其他元信息，这些信息与给定资源的整个集合相关。

要创建资源集合，您应该在使用创建资源时使用 --collection 标志。或者，在资源名称中包含单词 Collection 将指示 Laravel 应创建集合资源。集合资源扩展了 Illuminate\Http\Resources\Json\ResourceCollection 类

1php artisan make:resource User --collection
2 
3php artisan make:resource UserCollection

php artisan make:resource User --collection

php artisan make:resource UserCollection

概念概述

这是资源和资源集合的高级概述。强烈建议您阅读本文档的其他部分，以更深入地了解资源为您提供的自定义和强大功能。

在深入了解编写资源时可用的所有选项之前，让我们首先从高层次了解资源在 Laravel 中的使用方式。资源类表示需要转换为 JSON 结构的单个模型。例如，这是一个简单的 UserResource 资源类

 1<?php
 2 
 3namespace App\Http\Resources;
 4 
 5use Illuminate\Http\Request;
 6use Illuminate\Http\Resources\Json\JsonResource;
 7 
 8class UserResource extends JsonResource
 9{
10    /**
11     * Transform the resource into an array.
12     *
13     * @return array<string, mixed>
14     */
15    public function toArray(Request $request): array
16    {
17        return [
18            'id' => $this->id,
19            'name' => $this->name,
20            'email' => $this->email,
21            'created_at' => $this->created_at,
22            'updated_at' => $this->updated_at,
23        ];
24    }
25}

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }
}

每个资源类都定义了一个 toArray 方法，该方法返回当资源作为路由或控制器方法的响应返回时应转换为 JSON 的属性数组。

请注意，我们可以直接从 $this 变量访问模型属性。这是因为资源类将自动将属性和方法访问代理到基础模型，以便于访问。一旦定义了资源，就可以从路由或控制器返回它。资源通过其构造函数接受基础模型实例

1use App\Http\Resources\UserResource;
2use App\Models\User;
3 
4Route::get('/user/{id}', function (string $id) {
5    return new UserResource(User::findOrFail($id));
6});

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/user/{id}', function (string $id) {
    return new UserResource(User::findOrFail($id));
});

资源集合

如果您返回的是资源集合或分页响应，则应在使用路由或控制器中创建资源实例时使用资源类提供的 collection 方法

1use App\Http\Resources\UserResource;
2use App\Models\User;
3 
4Route::get('/users', function () {
5    return UserResource::collection(User::all());
6});

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/users', function () {
    return UserResource::collection(User::all());
});

请注意，这不允许添加可能需要与集合一起返回的任何自定义元数据。如果您想自定义资源集合响应，您可以创建专用资源来表示集合

1php artisan make:resource UserCollection

php artisan make:resource UserCollection

生成资源集合类后，您可以轻松定义应包含在响应中的任何元数据

 1<?php
 2 
 3namespace App\Http\Resources;
 4 
 5use Illuminate\Http\Request;
 6use Illuminate\Http\Resources\Json\ResourceCollection;
 7 
 8class UserCollection extends ResourceCollection
 9{
10    /**
11     * Transform the resource collection into an array.
12     *
13     * @return array<int|string, mixed>
14     */
15    public function toArray(Request $request): array
16    {
17        return [
18            'data' => $this->collection,
19            'links' => [
20                'self' => 'link-value',
21            ],
22        ];
23    }
24}

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @return array<int|string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'data' => $this->collection,
            'links' => [
                'self' => 'link-value',
            ],
        ];
    }
}

定义资源集合后，可以从路由或控制器返回它

1use App\Http\Resources\UserCollection;
2use App\Models\User;
3 
4Route::get('/users', function () {
5    return new UserCollection(User::all());
6});

use App\Http\Resources\UserCollection;
use App\Models\User;

Route::get('/users', function () {
    return new UserCollection(User::all());
});

保留集合键

从路由返回资源集合时，Laravel 会重置集合的键，使其按数字顺序排列。但是，您可以向资源类添加 preserveKeys 属性，以指示是否应保留集合的原始键

 1<?php
 2 
 3namespace App\Http\Resources;
 4 
 5use Illuminate\Http\Resources\Json\JsonResource;
 6 
 7class UserResource extends JsonResource
 8{
 9    /**
10     * Indicates if the resource's collection keys should be preserved.
11     *
12     * @var bool
13     */
14    public $preserveKeys = true;
15}

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * Indicates if the resource's collection keys should be preserved.
     *
     * @var bool
     */
    public $preserveKeys = true;
}

当 preserveKeys 属性设置为 true 时，从路由或控制器返回集合时将保留集合键

1use App\Http\Resources\UserResource;
2use App\Models\User;
3 
4Route::get('/users', function () {
5    return UserResource::collection(User::all()->keyBy->id);
6});

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/users', function () {
    return UserResource::collection(User::all()->keyBy->id);
});

自定义底层资源类

通常，资源集合的 $this->collection 属性会自动填充，方法是将集合的每个项目映射到其单数资源类。单数资源类假定为集合的类名，不带类名末尾的 Collection 部分。此外，根据您的个人喜好，单数资源类可能会或可能不会以 Resource 为后缀。

例如，UserCollection 将尝试将给定的用户实例映射到 UserResource 资源。要自定义此行为，您可以覆盖资源集合的 $collects 属性

 1<?php
 2 
 3namespace App\Http\Resources;
 4 
 5use Illuminate\Http\Resources\Json\ResourceCollection;
 6 
 7class UserCollection extends ResourceCollection
 8{
 9    /**
10     * The resource that this resource collects.
11     *
12     * @var string
13     */
14    public $collects = Member::class;
15}

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * The resource that this resource collects.
     *
     * @var string
     */
    public $collects = Member::class;
}

编写资源

如果您尚未阅读概念概述，强烈建议您在继续阅读本文档之前这样做。

资源只需要将给定的模型转换为数组。因此，每个资源都包含一个 toArray 方法，该方法将模型的属性转换为 API 友好的数组，可以从应用程序的路由或控制器返回

 1<?php
 2 
 3namespace App\Http\Resources;
 4 
 5use Illuminate\Http\Request;
 6use Illuminate\Http\Resources\Json\JsonResource;
 7 
 8class UserResource extends JsonResource
 9{
10    /**
11     * Transform the resource into an array.
12     *
13     * @return array<string, mixed>
14     */
15    public function toArray(Request $request): array
16    {
17        return [
18            'id' => $this->id,
19            'name' => $this->name,
20            'email' => $this->email,
21            'created_at' => $this->created_at,
22            'updated_at' => $this->updated_at,
23        ];
24    }
25}

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }
}

定义资源后，可以直接从路由或控制器返回它

1use App\Http\Resources\UserResource;
2use App\Models\User;
3 
4Route::get('/user/{id}', function (string $id) {
5    return new UserResource(User::findOrFail($id));
6});

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/user/{id}', function (string $id) {
    return new UserResource(User::findOrFail($id));
});

关系

如果您想在响应中包含相关资源，可以将它们添加到资源 toArray 方法返回的数组中。在此示例中，我们将使用 PostResource 资源的 collection 方法将用户的博客文章添加到资源响应中

 1use App\Http\Resources\PostResource;
 2use Illuminate\Http\Request;
 3 
 4/**
 5 * Transform the resource into an array.
 6 *
 7 * @return array<string, mixed>
 8 */
 9public function toArray(Request $request): array
10{
11    return [
12        'id' => $this->id,
13        'name' => $this->name,
14        'email' => $this->email,
15        'posts' => PostResource::collection($this->posts),
16        'created_at' => $this->created_at,
17        'updated_at' => $this->updated_at,
18    ];
19}

use App\Http\Resources\PostResource;
use Illuminate\Http\Request;

/**
 * Transform the resource into an array.
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'posts' => PostResource::collection($this->posts),
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

如果您只想在关系已加载时才包含关系，请查看有关条件关系的文档。

资源集合

虽然资源将单个模型转换为数组，但资源集合将模型集合转换为数组。但是，并非绝对必要为每个模型定义资源集合类，因为所有资源都提供 collection 方法来动态生成“即席”资源集合

1use App\Http\Resources\UserResource;
2use App\Models\User;
3 
4Route::get('/users', function () {
5    return UserResource::collection(User::all());
6});

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/users', function () {
    return UserResource::collection(User::all());
});

但是，如果您需要自定义与集合一起返回的元数据，则必须定义自己的资源集合

 1<?php
 2 
 3namespace App\Http\Resources;
 4 
 5use Illuminate\Http\Request;
 6use Illuminate\Http\Resources\Json\ResourceCollection;
 7 
 8class UserCollection extends ResourceCollection
 9{
10    /**
11     * Transform the resource collection into an array.
12     *
13     * @return array<string, mixed>
14     */
15    public function toArray(Request $request): array
16    {
17        return [
18            'data' => $this->collection,
19            'links' => [
20                'self' => 'link-value',
21            ],
22        ];
23    }
24}

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'data' => $this->collection,
            'links' => [
                'self' => 'link-value',
            ],
        ];
    }
}

与单数资源一样，资源集合可以直接从路由或控制器返回

1use App\Http\Resources\UserCollection;
2use App\Models\User;
3 
4Route::get('/users', function () {
5    return new UserCollection(User::all());
6});

use App\Http\Resources\UserCollection;
use App\Models\User;

Route::get('/users', function () {
    return new UserCollection(User::all());
});

数据包装

默认情况下，当资源响应转换为 JSON 时，最外层的资源会包装在 data 键中。因此，例如，典型的资源集合响应如下所示

 1{
 2    "data": [
 3        {
 4            "id": 1,
 5            "name": "Eladio Schroeder Sr.",
 6            "email": "[email protected]"
 7        },
 8        {
 9            "id": 2,
10            "name": "Liliana Mayert",
11            "email": "[email protected]"
12        }
13    ]
14}

{
    "data": [
        {
            "id": 1,
            "name": "Eladio Schroeder Sr.",
            "email": "[email protected]"
        },
        {
            "id": 2,
            "name": "Liliana Mayert",
            "email": "[email protected]"
        }
    ]
}

如果您想禁用最外层资源的包装，则应在基本 Illuminate\Http\Resources\Json\JsonResource 类上调用 withoutWrapping 方法。通常，您应该从 AppServiceProvider 或另一个服务提供者调用此方法，该服务提供者在对应用程序的每个请求上加载

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Illuminate\Http\Resources\Json\JsonResource;
 6use Illuminate\Support\ServiceProvider;
 7 
 8class AppServiceProvider extends ServiceProvider
 9{
10    /**
11     * Register any application services.
12     */
13    public function register(): void
14    {
15        // ...
16    }
17 
18    /**
19     * Bootstrap any application services.
20     */
21    public function boot(): void
22    {
23        JsonResource::withoutWrapping();
24    }
25}

<?php

namespace App\Providers;

use Illuminate\Http\Resources\Json\JsonResource;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        // ...
    }

    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        JsonResource::withoutWrapping();
    }
}

withoutWrapping 方法仅影响最外层响应，不会删除您手动添加到自己的资源集合中的 data 键。

包装嵌套资源

您可以完全自由地决定如何包装资源的关联。如果您希望所有资源集合都包装在 data 键中，无论它们的嵌套如何，您都应该为每个资源定义一个资源集合类，并在 data 键中返回集合。

您可能想知道这是否会导致最外层资源包装在两个 data 键中。别担心，Laravel 永远不会让您的资源意外地被双重包装，因此您不必担心您正在转换的资源集合的嵌套级别

 1<?php
 2 
 3namespace App\Http\Resources;
 4 
 5use Illuminate\Http\Resources\Json\ResourceCollection;
 6 
 7class CommentsCollection extends ResourceCollection
 8{
 9    /**
10     * Transform the resource collection into an array.
11     *
12     * @return array<string, mixed>
13     */
14    public function toArray(Request $request): array
15    {
16        return ['data' => $this->collection];
17    }
18}

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

class CommentsCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return ['data' => $this->collection];
    }
}

数据包装和分页

当通过资源响应返回分页集合时，即使已调用 withoutWrapping 方法，Laravel 也会将您的资源数据包装在 data 键中。这是因为分页响应始终包含 meta 和 links 键，其中包含有关分页器状态的信息

 1{
 2    "data": [
 3        {
 4            "id": 1,
 5            "name": "Eladio Schroeder Sr.",
 6            "email": "[email protected]"
 7        },
 8        {
 9            "id": 2,
10            "name": "Liliana Mayert",
11            "email": "[email protected]"
12        }
13    ],
14    "links":{
15        "first": "http://example.com/users?page=1",
16        "last": "http://example.com/users?page=1",
17        "prev": null,
18        "next": null
19    },
20    "meta":{
21        "current_page": 1,
22        "from": 1,
23        "last_page": 1,
24        "path": "http://example.com/users",
25        "per_page": 15,
26        "to": 10,
27        "total": 10
28    }
29}

{
    "data": [
        {
            "id": 1,
            "name": "Eladio Schroeder Sr.",
            "email": "[email protected]"
        },
        {
            "id": 2,
            "name": "Liliana Mayert",
            "email": "[email protected]"
        }
    ],
    "links":{
        "first": "http://example.com/users?page=1",
        "last": "http://example.com/users?page=1",
        "prev": null,
        "next": null
    },
    "meta":{
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://example.com/users",
        "per_page": 15,
        "to": 10,
        "total": 10
    }
}

分页

您可以将 Laravel 分页器实例传递给资源的 collection 方法或自定义资源集合

1use App\Http\Resources\UserCollection;
2use App\Models\User;
3 
4Route::get('/users', function () {
5    return new UserCollection(User::paginate());
6});

use App\Http\Resources\UserCollection;
use App\Models\User;

Route::get('/users', function () {
    return new UserCollection(User::paginate());
});

分页响应始终包含 meta 和 links 键，其中包含有关分页器状态的信息

 1{
 2    "data": [
 3        {
 4            "id": 1,
 5            "name": "Eladio Schroeder Sr.",
 6            "email": "[email protected]"
 7        },
 8        {
 9            "id": 2,
10            "name": "Liliana Mayert",
11            "email": "[email protected]"
12        }
13    ],
14    "links":{
15        "first": "http://example.com/users?page=1",
16        "last": "http://example.com/users?page=1",
17        "prev": null,
18        "next": null
19    },
20    "meta":{
21        "current_page": 1,
22        "from": 1,
23        "last_page": 1,
24        "path": "http://example.com/users",
25        "per_page": 15,
26        "to": 10,
27        "total": 10
28    }
29}

{
    "data": [
        {
            "id": 1,
            "name": "Eladio Schroeder Sr.",
            "email": "[email protected]"
        },
        {
            "id": 2,
            "name": "Liliana Mayert",
            "email": "[email protected]"
        }
    ],
    "links":{
        "first": "http://example.com/users?page=1",
        "last": "http://example.com/users?page=1",
        "prev": null,
        "next": null
    },
    "meta":{
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://example.com/users",
        "per_page": 15,
        "to": 10,
        "total": 10
    }
}

自定义分页信息

如果您想自定义分页响应的 links 或 meta 键中包含的信息，您可以在资源上定义 paginationInformation 方法。此方法将接收 $paginated 数据和 $default 信息的数组，该数组是包含 links 和 meta 键的数组

 1/**
 2 * Customize the pagination information for the resource.
 3 *
 4 * @param  \Illuminate\Http\Request  $request
 5 * @param  array $paginated
 6 * @param  array $default
 7 * @return array
 8 */
 9public function paginationInformation($request, $paginated, $default)
10{
11    $default['links']['custom'] = 'https://example.com';
12 
13    return $default;
14}

/**
 * Customize the pagination information for the resource.
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  array $paginated
 * @param  array $default
 * @return array
 */
public function paginationInformation($request, $paginated, $default)
{
    $default['links']['custom'] = 'https://example.com';

    return $default;
}

条件属性

有时您可能希望仅在满足给定条件时才在资源响应中包含属性。例如，您可能希望仅在当前用户是“管理员”时才包含值。Laravel 提供了各种辅助方法来帮助您解决这种情况。when 方法可用于有条件地向资源响应添加属性

 1/**
 2 * Transform the resource into an array.
 3 *
 4 * @return array<string, mixed>
 5 */
 6public function toArray(Request $request): array
 7{
 8    return [
 9        'id' => $this->id,
10        'name' => $this->name,
11        'email' => $this->email,
12        'secret' => $this->when($request->user()->isAdmin(), 'secret-value'),
13        'created_at' => $this->created_at,
14        'updated_at' => $this->updated_at,
15    ];
16}

/**
 * Transform the resource into an array.
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'secret' => $this->when($request->user()->isAdmin(), 'secret-value'),
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

在此示例中，只有在经过身份验证的用户的 isAdmin 方法返回 true 时，才会在最终资源响应中返回 secret 键。如果该方法返回 false，则在将其发送到客户端之前，将从资源响应中删除 secret 键。when 方法允许您表达性地定义资源，而无需在构建数组时求助于条件语句。

when 方法还接受闭包作为其第二个参数，允许您仅在给定条件为 true 时才计算结果值

1'secret' => $this->when($request->user()->isAdmin(), function () {
2    return 'secret-value';
3}),

'secret' => $this->when($request->user()->isAdmin(), function () {
    return 'secret-value';
}),

whenHas 方法可用于在属性实际存在于底层模型上时包含属性

1'name' => $this->whenHas('name'),

'name' => $this->whenHas('name'),

此外，如果属性不为 null，则可以使用 whenNotNull 方法在资源响应中包含属性

1'name' => $this->whenNotNull($this->name),

'name' => $this->whenNotNull($this->name),

合并条件属性

有时您可能有多个属性应仅在基于相同条件时才包含在资源响应中。在这种情况下，您可以使用 mergeWhen 方法仅在给定条件为 true 时才将属性包含在响应中

 1/**
 2 * Transform the resource into an array.
 3 *
 4 * @return array<string, mixed>
 5 */
 6public function toArray(Request $request): array
 7{
 8    return [
 9        'id' => $this->id,
10        'name' => $this->name,
11        'email' => $this->email,
12        $this->mergeWhen($request->user()->isAdmin(), [
13            'first-secret' => 'value',
14            'second-secret' => 'value',
15        ]),
16        'created_at' => $this->created_at,
17        'updated_at' => $this->updated_at,
18    ];
19}

/**
 * Transform the resource into an array.
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        $this->mergeWhen($request->user()->isAdmin(), [
            'first-secret' => 'value',
            'second-secret' => 'value',
        ]),
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

同样，如果给定条件为 false，则在将其发送到客户端之前，将从资源响应中删除这些属性。

mergeWhen 方法不应在混合字符串键和数字键的数组中使用。此外，它不应在具有非顺序排序的数字键的数组中使用。

条件关系

除了有条件地加载属性外，您还可以根据关系是否已加载到模型上有条件地在资源响应中包含关系。这允许您的控制器决定应在模型上加载哪些关系，并且您的资源可以轻松地仅在实际加载它们时才包含它们。最终，这使得更容易避免资源中的“N+1”查询问题。

whenLoaded 方法可用于有条件地加载关系。为了避免不必要地加载关系，此方法接受关系的名称而不是关系本身

 1use App\Http\Resources\PostResource;
 2 
 3/**
 4 * Transform the resource into an array.
 5 *
 6 * @return array<string, mixed>
 7 */
 8public function toArray(Request $request): array
 9{
10    return [
11        'id' => $this->id,
12        'name' => $this->name,
13        'email' => $this->email,
14        'posts' => PostResource::collection($this->whenLoaded('posts')),
15        'created_at' => $this->created_at,
16        'updated_at' => $this->updated_at,
17    ];
18}

use App\Http\Resources\PostResource;

/**
 * Transform the resource into an array.
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'posts' => PostResource::collection($this->whenLoaded('posts')),
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

在此示例中，如果关系尚未加载，则在将其发送到客户端之前，将从资源响应中删除 posts 键。

条件关系计数

除了有条件地包含关系外，您还可以根据关系的计数是否已加载到模型上有条件地在资源响应中包含关系“计数”

1new UserResource($user->loadCount('posts'));

new UserResource($user->loadCount('posts'));

whenCounted 方法可用于有条件地在资源响应中包含关系的计数。如果关系的计数不存在，此方法可避免不必要地包含属性

 1/**
 2 * Transform the resource into an array.
 3 *
 4 * @return array<string, mixed>
 5 */
 6public function toArray(Request $request): array
 7{
 8    return [
 9        'id' => $this->id,
10        'name' => $this->name,
11        'email' => $this->email,
12        'posts_count' => $this->whenCounted('posts'),
13        'created_at' => $this->created_at,
14        'updated_at' => $this->updated_at,
15    ];
16}

/**
 * Transform the resource into an array.
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'posts_count' => $this->whenCounted('posts'),
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

在此示例中，如果 posts 关系的计数尚未加载，则在将其发送到客户端之前，将从资源响应中删除 posts_count 键。

其他类型的聚合，例如 avg、sum、min 和 max 也可以使用 whenAggregated 方法有条件地加载

1'words_avg' => $this->whenAggregated('posts', 'words', 'avg'),
2'words_sum' => $this->whenAggregated('posts', 'words', 'sum'),
3'words_min' => $this->whenAggregated('posts', 'words', 'min'),
4'words_max' => $this->whenAggregated('posts', 'words', 'max'),

'words_avg' => $this->whenAggregated('posts', 'words', 'avg'),
'words_sum' => $this->whenAggregated('posts', 'words', 'sum'),
'words_min' => $this->whenAggregated('posts', 'words', 'min'),
'words_max' => $this->whenAggregated('posts', 'words', 'max'),

条件透视信息

除了在资源响应中有条件地包含关系信息外，您还可以使用 whenPivotLoaded 方法有条件地包含来自多对多关系中间表的数据。whenPivotLoaded 方法接受透视表的名称作为其第一个参数。第二个参数应是一个闭包，如果透视信息在模型上可用，则返回要返回的值

 1/**
 2 * Transform the resource into an array.
 3 *
 4 * @return array<string, mixed>
 5 */
 6public function toArray(Request $request): array
 7{
 8    return [
 9        'id' => $this->id,
10        'name' => $this->name,
11        'expires_at' => $this->whenPivotLoaded('role_user', function () {
12            return $this->pivot->expires_at;
13        }),
14    ];
15}

/**
 * Transform the resource into an array.
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'expires_at' => $this->whenPivotLoaded('role_user', function () {
            return $this->pivot->expires_at;
        }),
    ];
}

如果您的关系正在使用自定义中间表模型，您可以将中间表模型的实例作为 whenPivotLoaded 方法的第一个参数传递

1'expires_at' => $this->whenPivotLoaded(new Membership, function () {
2    return $this->pivot->expires_at;
3}),

'expires_at' => $this->whenPivotLoaded(new Membership, function () {
    return $this->pivot->expires_at;
}),

如果您的中间表正在使用 pivot 以外的访问器，您可以使用 whenPivotLoadedAs 方法

 1/**
 2 * Transform the resource into an array.
 3 *
 4 * @return array<string, mixed>
 5 */
 6public function toArray(Request $request): array
 7{
 8    return [
 9        'id' => $this->id,
10        'name' => $this->name,
11        'expires_at' => $this->whenPivotLoadedAs('subscription', 'role_user', function () {
12            return $this->subscription->expires_at;
13        }),
14    ];
15}

/**
 * Transform the resource into an array.
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'expires_at' => $this->whenPivotLoadedAs('subscription', 'role_user', function () {
            return $this->subscription->expires_at;
        }),
    ];
}

添加元数据

一些 JSON API 标准要求向您的资源和资源集合响应添加元数据。这通常包括指向资源或相关资源的 links 之类的内容，或关于资源本身的元数据。如果您需要返回关于资源的附加元数据，请将其包含在 toArray 方法中。例如，您可以在转换资源集合时包含 links 信息

 1/**
 2 * Transform the resource into an array.
 3 *
 4 * @return array<string, mixed>
 5 */
 6public function toArray(Request $request): array
 7{
 8    return [
 9        'data' => $this->collection,
10        'links' => [
11            'self' => 'link-value',
12        ],
13    ];
14}

/**
 * Transform the resource into an array.
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'data' => $this->collection,
        'links' => [
            'self' => 'link-value',
        ],
    ];
}

从资源返回附加元数据时，您永远不必担心意外覆盖 Laravel 在返回分页响应时自动添加的 links 或 meta 键。您定义的任何附加 links 都将与分页器提供的链接合并。

顶级元数据

有时您可能希望仅在资源是最外层返回的资源时才在资源响应中包含某些元数据。通常，这包括关于整个响应的元信息。要定义此元数据，请向您的资源类添加 with 方法。此方法应返回要与资源响应一起包含的元数据数组，仅当资源是最外层转换的资源时才包含

 1<?php
 2 
 3namespace App\Http\Resources;
 4 
 5use Illuminate\Http\Resources\Json\ResourceCollection;
 6 
 7class UserCollection extends ResourceCollection
 8{
 9    /**
10     * Transform the resource collection into an array.
11     *
12     * @return array<string, mixed>
13     */
14    public function toArray(Request $request): array
15    {
16        return parent::toArray($request);
17    }
18 
19    /**
20     * Get additional data that should be returned with the resource array.
21     *
22     * @return array<string, mixed>
23     */
24    public function with(Request $request): array
25    {
26        return [
27            'meta' => [
28                'key' => 'value',
29            ],
30        ];
31    }
32}

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return parent::toArray($request);
    }

    /**
     * Get additional data that should be returned with the resource array.
     *
     * @return array<string, mixed>
     */
    public function with(Request $request): array
    {
        return [
            'meta' => [
                'key' => 'value',
            ],
        ];
    }
}

在构建资源时添加元数据

您还可以在路由或控制器中构建资源实例时添加顶级数据。additional 方法（所有资源都可用）接受应添加到资源响应的数据数组

1return (new UserCollection(User::all()->load('roles')))
2    ->additional(['meta' => [
3        'key' => 'value',
4    ]]);

return (new UserCollection(User::all()->load('roles')))
    ->additional(['meta' => [
        'key' => 'value',
    ]]);

资源响应

正如您已经阅读的那样，资源可以直接从路由和控制器返回

1use App\Http\Resources\UserResource;
2use App\Models\User;
3 
4Route::get('/user/{id}', function (string $id) {
5    return new UserResource(User::findOrFail($id));
6});

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/user/{id}', function (string $id) {
    return new UserResource(User::findOrFail($id));
});

但是，有时您可能需要在发送到客户端之前自定义传出的 HTTP 响应。有两种方法可以实现此目的。首先，您可以将 response 方法链接到资源。此方法将返回 Illuminate\Http\JsonResponse 实例，使您可以完全控制响应的标头

1use App\Http\Resources\UserResource;
2use App\Models\User;
3 
4Route::get('/user', function () {
5    return (new UserResource(User::find(1)))
6        ->response()
7        ->header('X-Value', 'True');
8});

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/user', function () {
    return (new UserResource(User::find(1)))
        ->response()
        ->header('X-Value', 'True');
});

或者，您可以在资源本身中定义 withResponse 方法。当资源作为响应中最外层资源返回时，将调用此方法

 1<?php
 2 
 3namespace App\Http\Resources;
 4 
 5use Illuminate\Http\JsonResponse;
 6use Illuminate\Http\Request;
 7use Illuminate\Http\Resources\Json\JsonResource;
 8 
 9class UserResource extends JsonResource
10{
11    /**
12     * Transform the resource into an array.
13     *
14     * @return array<string, mixed>
15     */
16    public function toArray(Request $request): array
17    {
18        return [
19            'id' => $this->id,
20        ];
21    }
22 
23    /**
24     * Customize the outgoing response for the resource.
25     */
26    public function withResponse(Request $request, JsonResponse $response): void
27    {
28        $response->header('X-Value', 'True');
29    }
30}

<?php

namespace App\Http\Resources;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
        ];
    }

    /**
     * Customize the outgoing response for the resource.
     */
    public function withResponse(Request $request, JsonResponse $response): void
    {
        $response->header('X-Value', 'True');
    }
}

序言

入门指南

架构概念

基础知识

深入了解

安全

数据库

Eloquent ORM

测试

包

Eloquent：API 资源

简介

生成资源

资源集合

概念概述

资源集合

保留集合键

自定义底层资源类

编写资源

关系

资源集合

数据包装

包装嵌套资源

条件属性

合并条件属性

条件关系

条件关系计数

条件透视信息

添加元数据

顶级元数据

在构建资源时添加元数据

资源响应

产品

包

资源