Eloquent：API 资源

介绍
生成资源
概念概述
- 资源集合
写作资源
资源响应

介绍

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

当然，你也可以使用其 toJson 方法；但是，Eloquent 资源对模型及其关系的 JSON 序列化提供了更精细、更强大的控制。

生成资源

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

1
php
工匠

制作：资源

用户资源
php artisan make：resource 用户资源

资源集合

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

要创建资源集合，您应该使用 --collection 创建资源时添加标志。或者，包括单词 Collection 资源名称中的表示 Laravel 应该创建一个集合资源。集合资源扩展了 Illuminate\Http\Resources\Json\ResourceCollection 班级：

1
php
工匠

制作：资源

用户

- 收藏
2
3
php
工匠

制作：资源

用户集合
php artisan make：资源用户 --collection php artisan make：资源用户集合

概念概述

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

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

1
2
3
命名空间
应用程序\Http\资源；
4
5
使用
照亮\Http\
要求
;
6
使用
照亮\Http\Resources\Json\
Json资源
;
7
8
班级

用户资源

延伸

Json资源
9
{
10

/**
11
* 将资源转换为数组。
12
*
13
*
@返回

大批
<
细绳
, 混合>
14

*/
15

民众

功能

数组
（
要求

$请求
）
:

大批
16
{
17

返回
[
18

‘
ID
‘

=>

$this
->id
,
19

‘
姓名
‘

=>

$this
->名称
,
20

‘
电子邮件
‘

=>

$this
->电子邮件
,
21

‘
创建于
‘

=>

$this
创建于
,
22

‘
更新于
‘

=>

$this
->已更新
,
23
]；
24
}
25
}
 */ 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 变量。这是因为资源类会自动将属性和方法访问代理到底层模型，以方便访问。一旦定义了资源，它就可以从路由或控制器返回。资源通过其构造函数接受底层模型实例：

1
使用
应用程序\Http\资源\
用户资源
;
2
使用
应用程序\模型\
用户
;
3
4
路线
::
得到
（
‘
/用户身份}
‘
,
功能

（
细绳

$id
）
{
5

返回

新的

用户资源
（
用户
::
查找或失败
（
$id
））；
6
});
使用 App\Http\Resources\UserResource；使用 App\Models\User；Route::get('/user/{id}'，函数（字符串 $id）{返回新的 UserResource（User::findOrFail($id)); });

资源集合

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

1
使用
应用程序\Http\资源\
用户资源
;
2
使用
应用程序\模型\
用户
;
3
4
路线
::
得到
（
‘
/用户
‘
,
功能

（）
{
5

返回

用户资源
::
收藏
（
用户
::
全部
（））；
6
});
使用 App\Http\Resources\UserResource；使用 App\Models\User；Route::get('/users'，函数 () {return UserResource::collection(User::all());});

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

1
php
工匠

制作：资源

用户集合
php artisan make：资源用户集合

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

1
2
3
命名空间
应用程序\Http\资源；
4
5
使用
照亮\Http\
要求
;
6
使用
照亮\Http\Resources\Json\
资源集合
;
7
8
班级

用户集合

延伸

资源集合
9
{
10

/**
11
* 将资源集合转换为数组。
12
*
13
*
@返回

大批
<
整数
|
细绳
, 混合>
14

*/
15

民众

功能

数组
（
要求

$请求
）
:

大批
16
{
17

返回
[
18

‘
数据
‘

=>

$this
->收藏
,
19

‘
链接
‘

=>
[
20

‘
自己
‘

=>

‘
链接值
‘
,
21
]，
22
]；
23
}
24
}
 */ public function toArray(Request $request): array { return [ 'data' => $this->collection, 'links' => [ 'self' => 'link-value', ], ]; } }

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

1
使用
应用程序\Http\资源\
用户集合
;
2
使用
应用程序\模型\
用户
;
3
4
路线
::
得到
（
‘
/用户
‘
,
功能

（）
{
5

返回

新的

用户集合
（
用户
::
全部
（））；
6
});
使用 App\Http\Resources\UserCollection; 使用 App\Models\User; Route::get('/users', function () { return new UserCollection(User::all()); });

保存集合键

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

1
2
3
命名空间
应用程序\Http\资源；
4
5
使用
照亮\Http\Resources\Json\
Json资源
;
6
7
班级

用户资源

延伸

Json资源
8
{
9

/**
10
* 表示是否应该保留资源的集合密钥。
11
*
12
*
@我们的

布尔值
13

*/
14

民众

$preserveKeys

=

真的
;
15
}

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

1
使用
应用程序\Http\资源\
用户资源
;
2
使用
应用程序\模型\
用户
;
3
4
路线
::
得到
（
‘
/用户
‘
,
功能

（）
{
5

返回

用户资源
::
收藏
（
用户
::
全部
（）
->keyBy->id
（英文）：
6
});
使用 App\Http\Resources\UserResource；使用 App\Models\User；Route::get('/users'，函数 () {返回 UserResource::collection(User::all()->keyBy->id); });

自定义底层资源类

通常情况下， $this->collection 资源集合的属性会自动填充将集合中的每个项目映射到其单个资源类的结果。单个资源类被认为是集合的类名，不带尾随 Collection 类名的一部分。此外，根据您的个人喜好，单数资源类可能会或可能不会带有后缀 Resource 。

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

1
2
3
命名空间
应用程序\Http\资源；
4
5
使用
照亮\Http\Resources\Json\
资源集合
;
6
7
班级

用户集合

延伸

资源集合
8
{
9

/**
10
* 该资源收集的资源。
11
*
12
*
@我们的

细绳
13

*/
14

民众

$收集

=

成员
::
班级
;
15
}

写作资源

如果你还没有读过概念概述，我们强烈建议您在继续阅读本文档之前这样做。

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

1
2
3
命名空间
应用程序\Http\资源；
4
5
使用
照亮\Http\
要求
;
6
使用
照亮\Http\Resources\Json\
Json资源
;
7
8
班级

用户资源

延伸

Json资源
9
{
10

/**
11
* 将资源转换为数组。
12
*
13
*
@返回

大批
<
细绳
, 混合>
14

*/
15

民众

功能

数组
（
要求

$请求
）
:

大批
16
{
17

返回
[
18

‘
ID
‘

=>

$this
->id
,
19

‘
姓名
‘

=>

$this
->名称
,
20

‘
电子邮件
‘

=>

$this
->电子邮件
,
21

‘
创建于
‘

=>

$this
创建于
,
22

‘
更新于
‘

=>

$this
->已更新
,
23
]；
24
}
25
}
 */ 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, ]; } }

一旦定义了资源，就可以直接从路由或控制器返回：

1
使用
应用程序\Http\资源\
用户资源
;
2
使用
应用程序\模型\
用户
;
3
4
路线
::
得到
（
‘
/用户身份}
‘
,
功能

（
细绳

$id
）
{
5

返回

新的

用户资源
（
用户
::
查找或失败
（
$id
））；
6
});
使用 App\Http\Resources\UserResource；使用 App\Models\User；Route::get('/user/{id}'，函数（字符串 $id）{返回新的 UserResource（User::findOrFail($id)); });

关系

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

1
使用
应用程序\Http\资源\
帖子资源
;
2
使用
照亮\Http\
要求
;
3
4
/**
5
* 将资源转换为数组。
6
*
7
*
@返回

大批
<
细绳
, 混合>
8

*/
9
民众

功能

数组
（
要求

$请求
）
:

大批
10
{
11

返回
[
12

‘
ID
‘

=>

$this
->id
,
13

‘
姓名
‘

=>

$this
->名称
,
14

‘
电子邮件
‘

=>

$this
->电子邮件
,
15

‘
帖子
‘

=>

帖子资源
::
收藏
（
$this
->帖子
),
16

‘
创建于
‘

=>

$this
创建于
,
17

‘
更新于
‘

=>

$this
->已更新
,
18
]；
19
}
使用 App\Http\Resources\PostResource; 使用 Illuminate\Http\Request; /** * 将资源转换为数组。 * * @return array */ 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 方法动态生成“临时”资源集合：

1
使用
应用程序\Http\资源\
用户资源
;
2
使用
应用程序\模型\
用户
;
3
4
路线
::
得到
（
‘
/用户
‘
,
功能

（）
{
5

返回

用户资源
::
收藏
（
用户
::
全部
（））；
6
});
使用 App\Http\Resources\UserResource；使用 App\Models\User；Route::get('/users'，函数 () {return UserResource::collection(User::all());});

但是，如果您需要自定义随集合返回的元数据，则需要定义自己的资源集合：

1
2
3
命名空间
应用程序\Http\资源；
4
5
使用
照亮\Http\
要求
;
6
使用
照亮\Http\Resources\Json\
资源集合
;
7
8
班级

用户集合

延伸

资源集合
9
{
10

/**
11
* 将资源集合转换为数组。
12
*
13
*
@返回

大批
<
细绳
, 混合>
14

*/
15

民众

功能

数组
（
要求

$请求
）
:

大批
16
{
17

返回
[
18

‘
数据
‘

=>

$this
->收藏
,
19

‘
链接
‘

=>
[
20

‘
自己
‘

=>

‘
链接值
‘
,
21
]，
22
]；
23
}
24
}
 */ public function toArray(Request $request): array { return [ 'data' => $this->collection, 'links' => [ 'self' => 'link-value', ], ]; } }

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

1
使用
应用程序\Http\资源\
用户集合
;
2
使用
应用程序\模型\
用户
;
3
4
路线
::
得到
（
‘
/用户
‘
,
功能

（）
{
5

返回

新的

用户集合
（
用户
::
全部
（））；
6
});
使用 App\Http\Resources\UserCollection; 使用 App\Models\User; Route::get('/users', function () { return new UserCollection(User::all()); });

数据包装

默认情况下，最外层的资源被包裹在 data 当资源响应转换为 JSON 时，key 是关键。例如，典型的资源集合响应如下所示：

1
{
2

“数据”
：[
3
{
4

“ID”
:
1
,
5

“姓名”
:
“
埃拉迪奥·施罗德（老）
“
,
6

“电子邮件”
:
“
[电子邮件保护]
“
7
}，
8
{
9

“ID”
:
2
,
10

“姓名”
:
“
莉莉安娜·梅耶特
“
,
11

“电子邮件”
:
“
[电子邮件保护]
“
12
}
13
]
14
}
{
“数据”： [
{
“id”：1，
“姓名”：“Eladio Schroeder Sr.”,
“电子邮件”： ”
[电子邮件保护]
“
}，
{
“id”：2，
“名称”：“Liliana Mayert”，
“电子邮件”： ”
[电子邮件保护]
“
}
]
}

如果你想禁用最外层资源的包装，你应该调用 withoutWrapping 方法 Illuminate\Http\Resources\Json\JsonResource 类。通常，您应该从您的 AppServiceProvider 或其他服务提供商每次向应用程序发出请求时都会加载该内容：

1
2
3
命名空间
应用程序\提供商；
4
5
使用
照亮\Http\Resources\Json\
Json资源
;
6
使用
照亮\支持\
服务提供者
;
7
8
班级

应用服务提供商

延伸

服务提供者
9
{
10

/**
11
* 注册任何应用服务。
12

*/
13

民众

功能

登记
（）
:

空白
14
{
15

//
...
16
}
17
18

/**
19
* 引导任何应用服务。
20

*/
21

民众

功能

引导
（）
:

空白
22
{
23

Json资源
::
不带包装
（）；
24
}
25
}

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

包装嵌套资源

您可以完全自由地确定资源关系的包装方式。如果您希望将所有资源集合包装在 data 键，无论它们的嵌套如何，您都应该为每个资源定义一个资源集合类，并在 data 钥匙。

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

1
2
3
命名空间
应用程序\Http\资源；
4
5
使用
照亮\Http\Resources\Json\
资源集合
;
6
7
班级

评论收藏

延伸

资源集合
8
{
9

/**
10
* 将资源集合转换为数组。
11
*
12
*
@返回

大批
<
细绳
, 混合>
13

*/
14

民众

功能

数组
（
要求

$请求
）
:

大批
15
{
16

返回
[
‘
数据
‘

=>

$this
->收藏
]；
17
}
18
}
 */ public function toArray(Request $request): array { return ['data' => $this->collection]; } }

数据包装和分页

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

1
{
2

“数据”
：[
3
{
4

“ID”
:
1
,
5

“姓名”
:
“
埃拉迪奥·施罗德（老）
“
,
6

“电子邮件”
:
“
[电子邮件保护]
“
7
}，
8
{
9

“ID”
:
2
,
10

“姓名”
:
“
莉莉安娜·梅耶特
“
,
11

“电子邮件”
:
“
[电子邮件保护]
“
12
}
13
]，
14

“链接”
：{
15

“第一的”
:
“
http://example.com/users?page=1
“
,
16

“最后的”
:
“
http://example.com/users?page=1
“
,
17

“上一页”
:
无效的
,
18

“下一个”
:
无效的
19
}，
20

“元”
：{
21

“当前页面”
:
1
,
22

“从”
:
1
,
23

“最后一页”
:
1
,
24

“小路”
:
“
http://example.com/users
“
,
25

“每页”
:
15
,
26

“到”
:
10
,
27

“全部的”
:
10
28
}
29
}
{
“数据”： [
{
“id”：1，
“姓名”：“Eladio Schroeder Sr.”,
“电子邮件”： ”
[电子邮件保护]
“
}，
{
“id”：2，
“名称”：“Liliana Mayert”，
“电子邮件”： ”
[电子邮件保护]
“
}
]，
“链接”：{
“first”：“http://example.com/users?page=1”，
“last”：“http://example.com/users?page=1”，
“上一页”：空，
“下一个”：空
}，
“元”：{
“当前页”：1，
“来自”：1，
“最后一页”：1，
“路径”：“http://example.com/users”，
“每页”：15，
“至”：10，
“总计”：10
}
}

分页

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

1
使用
应用程序\Http\资源\
用户集合
;
2
使用
应用程序\模型\
用户
;
3
4
路线
::
得到
（
‘
/用户
‘
,
功能

（）
{
5

返回

新的

用户集合
（
用户
::
分页
（））；
6
});
使用 App\Http\Resources\UserCollection; 使用 App\Models\User; Route::get('/users', function () { return new UserCollection(User::paginate()); });

分页响应始终包含 meta 和 links 包含分页器状态信息的键：

1
{
2

“数据”
：[
3
{
4

“ID”
:
1
,
5

“姓名”
:
“
埃拉迪奥·施罗德（老）
“
,
6

“电子邮件”
:
“
[电子邮件保护]
“
7
}，
8
{
9

“ID”
:
2
,
10

“姓名”
:
“
莉莉安娜·梅耶特
“
,
11

“电子邮件”
:
“
[电子邮件保护]
“
12
}
13
]，
14

“链接”
：{
15

“第一的”
:
“
http://example.com/users?page=1
“
,
16

“最后的”
:
“
http://example.com/users?page=1
“
,
17

“上一页”
:
无效的
,
18

“下一个”
:
无效的
19
}，
20

“元”
：{
21

“当前页面”
:
1
,
22

“从”
:
1
,
23

“最后一页”
:
1
,
24

“小路”
:
“
http://example.com/users
“
,
25

“每页”
:
15
,
26

“到”
:
10
,
27

“全部的”
:
10
28
}
29
}
{
“数据”： [
{
“id”：1，
“姓名”：“Eladio Schroeder Sr.”,
“电子邮件”： ”
[电子邮件保护]
“
}，
{
“id”：2，
“名称”：“Liliana Mayert”，
“电子邮件”： ”
[电子邮件保护]
“
}
]，
“链接”：{
“first”：“http://example.com/users?page=1”，
“last”：“http://example.com/users?page=1”，
“上一页”：空，
“下一个”：空
}，
“元”：{
“当前页”：1，
“来自”：1，
“最后一页”：1，
“路径”：“http://example.com/users”，
“每页”：15，
“至”：10，
“总计”：10
}
}

自定义分页信息

如果您想自定义包含在 links 或者 meta 分页响应的键，你可以定义一个 paginationInformation 方法。此方法将接收 $paginated 数据和数组 $default 信息，它是一个包含 links 和 meta 键：

1
/**
2
* 自定义资源的分页信息。
3
*
4
*
@参数

\
照亮
\
Http
\
要求
$请求
5
*
@参数

大批
$分页
6
*
@参数

大批
$默认
7
*
@返回

大批
8

*/
9
民众

功能

分页信息
（
$请求
,
$分页
,
$默认
）
10
{
11

$默认
[
‘
链接
‘
][
‘
风俗
‘
]
=

‘
https://example.com
‘
;
12
13

返回

$默认
;
14
}
/** * 自定义资源的分页信息。 * * @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
* 将资源转换为数组。
3
*
4
*
@返回

大批
<
细绳
, 混合>
5

*/
6
民众

功能

数组
（
要求

$请求
）
:

大批
7
{
8

返回
[
9

‘
ID
‘

=>

$this
->id
,
10

‘
姓名
‘

=>

$this
->名称
,
11

‘
电子邮件
‘

=>

$this
->电子邮件
,
12

‘
秘密
‘

=>

$this
->
什么时候
（
$请求
->
用户
（）
->
管理员
（），
‘
秘密值
‘
),
13

‘
创建于
‘

=>

$this
创建于
,
14

‘
更新于
‘

=>

$this
->已更新
,
15
]；
16
}
/** * 将资源转换为数组。 * * @return array */ 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, ]; }

在此示例中， secret 仅当经过身份验证的用户的 isAdmin 方法返回 true . 如果该方法返回 false ，这 secret 在资源响应发送给客户端之前，密钥将被删除。 when 方法允许您在构建数组时表达地定义您的资源，而无需借助条件语句。

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

1
‘
秘密
‘

=>

$this
->
什么时候
（
$请求
->
用户
（）
->
管理员
（），
功能

（）
{
2

返回

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

这 whenHas 该方法可用于包含一个属性（如果它确实存在于底层模型中）：

1
‘
姓名
‘

=>

$this
->
何时有
（
‘
姓名
‘
),
'name' => $this->whenHas('name'),

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

1
‘
姓名
‘

=>

$this
->
当 NotNull 时
（
$this
->名称
),
'name' => $this->whenNotNull($this->name),

合并条件属性

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

1
/**
2
* 将资源转换为数组。
3
*
4
*
@返回

大批
<
细绳
, 混合>
5

*/
6
民众

功能

数组
（
要求

$请求
）
:

大批
7
{
8

返回
[
9

‘
ID
‘

=>

$this
->id
,
10

‘
姓名
‘

=>

$this
->名称
,
11

‘
电子邮件
‘

=>

$this
->电子邮件
,
12

$this
->
合并时间
（
$请求
->
用户
（）
->
管理员
（），[
13

‘
第一秘密
‘

=>

‘
价值
‘
,
14

‘
第二个秘密
‘

=>

‘
价值
‘
,
15
]),
16

‘
创建于
‘

=>

$this
创建于
,
17

‘
更新于
‘

=>

$this
->已更新
,
18
]；
19
}
/** * 将资源转换为数组。 * * @return array */ 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 方法可用于有条件地加载关系。为了避免不必要地加载关系，此方法接受关系的名称而不是关系本身：

1
使用
应用程序\Http\资源\
帖子资源
;
2
3
/**
4
* 将资源转换为数组。
5
*
6
*
@返回

大批
<
细绳
, 混合>
7

*/
8
民众

功能

数组
（
要求

$请求
）
:

大批
9
{
10

返回
[
11

‘
ID
‘

=>

$this
->id
,
12

‘
姓名
‘

=>

$this
->名称
,
13

‘
电子邮件
‘

=>

$this
->电子邮件
,
14

‘
帖子
‘

=>

帖子资源
::
收藏
（
$this
->
加载时
（
‘
帖子
‘
)),
15

‘
创建于
‘

=>

$this
创建于
,
16

‘
更新于
‘

=>

$this
->已更新
,
17
]；
18
}
使用 App\Http\Resources\PostResource; /** * 将资源转换为数组。 * * @return array */ 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 在将资源响应发送给客户端之前，密钥将被从资源响应中删除。

有条件的关系很重要

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

1
新的

用户资源
（
$用户
->
加载次数
（
‘
帖子
‘
））；
新的用户资源($user->loadCount('posts'));

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

1
/**
2
* 将资源转换为数组。
3
*
4
*
@返回

大批
<
细绳
, 混合>
5

*/
6
民众

功能

数组
（
要求

$请求
）
:

大批
7
{
8

返回
[
9

‘
ID
‘

=>

$this
->id
,
10

‘
姓名
‘

=>

$this
->名称
,
11

‘
电子邮件
‘

=>

$this
->电子邮件
,
12

‘
帖子数
‘

=>

$this
->
计算时间
（
‘
帖子
‘
),
13

‘
创建于
‘

=>

$this
创建于
,
14

‘
更新于
‘

=>

$this
->已更新
,
15
]；
16
}
/** * 将资源转换为数组。 * * @return array */ 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
‘
平均单词数
‘

=>

$this
->
聚合时
（
‘
帖子
‘
,
‘
字
‘
,
‘
平均
‘
),
2
‘
words_sum
‘

=>

$this
->
聚合时
（
‘
帖子
‘
,
‘
字
‘
,
‘
和
‘
),
3
‘
最少单词数
‘

=>

$this
->
聚合时
（
‘
帖子
‘
,
‘
字
‘
,
‘
分钟
‘
),
4
‘
words_max
‘

=>

$this
->
聚合时
（
‘
帖子
‘
,
‘
字
‘
,
‘
最大限度
‘
),
'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
* 将资源转换为数组。
3
*
4
*
@返回

大批
<
细绳
, 混合>
5

*/
6
民众

功能

数组
（
要求

$请求
）
:

大批
7
{
8

返回
[
9

‘
ID
‘

=>

$this
->id
,
10

‘
姓名
‘

=>

$this
->名称
,
11

‘
expires_at
‘

=>

$this
->
当 PivotLoaded
（
‘
role_user
‘
,
功能

（）
{
12

返回

$this
->pivot->expires_at
;
13
}),
14
]；
15
}
/** * 将资源转换为数组。 * * @return array */ 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
->
当 PivotLoaded
（
新的

会员资格
,
功能

（）
{
2

返回

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

如果您的中间表使用的是除 pivot ，您可以使用 whenPivotLoadedAs 方法：

1
/**
2
* 将资源转换为数组。
3
*
4
*
@返回

大批
<
细绳
, 混合>
5

*/
6
民众

功能

数组
（
要求

$请求
）
:

大批
7
{
8

返回
[
9

‘
ID
‘

=>

$this
->id
,
10

‘
姓名
‘

=>

$this
->名称
,
11

‘
expires_at
‘

=>

$this
->
当 PivotLoadedAs
（
‘
订阅
‘
,
‘
role_user
‘
,
功能

（）
{
12

返回

$this
订阅到期时间
;
13
}),
14
]；
15
}
/** * 将资源转换为数组。 * * @return array */ 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
* 将资源转换为数组。
3
*
4
*
@返回

大批
<
细绳
, 混合>
5

*/
6
民众

功能

数组
（
要求

$请求
）
:

大批
7
{
8

返回
[
9

‘
数据
‘

=>

$this
->收藏
,
10

‘
链接
‘

=>
[
11

‘
自己
‘

=>

‘
链接值
‘
,
12
]，
13
]；
14
}
/** * 将资源转换为数组。 * * @return array */ public function toArray(Request $request): array { return [ 'data' => $this->collection, 'links' => [ 'self' => 'link-value', ], ]; }

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

顶级元数据

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

1
2
3
命名空间
应用程序\Http\资源；
4
5
使用
照亮\Http\Resources\Json\
资源集合
;
6
7
班级

用户集合

延伸

资源集合
8
{
9

/**
10
* 将资源集合转换为数组。
11
*
12
*
@返回

大批
<
细绳
, 混合>
13

*/
14

民众

功能

数组
（
要求

$请求
）
:

大批
15
{
16

返回

父母
::
数组
（
$请求
（英文）：
17
}
18
19

/**
20
* 获取应与资源数组一起返回的附加数据。
21
*
22
*
@返回

大批
<
细绳
, 混合>
23

*/
24

民众

功能

和
（
要求

$请求
）
:

大批
25
{
26

返回
[
27

‘
元
‘

=>
[
28

‘
钥匙
‘

=>

‘
价值
‘
,
29
]，
30
]；
31
}
32
}
 */ public function toArray(Request $request): array { return parent::toArray($request); } /** * 获取应与资源数组一起返回的附加数据。 * * @return array */ public function with(Request $request): array { return [ 'meta' => [ 'key' => 'value', ], ]; } }

构建资源时添加元数据

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

1
返回
（
新的

用户集合
（
用户
::
全部
（）
->
加载
（
‘
角色
‘
）））
2

->
额外的
（[
‘
元
‘

=>
[
3

‘
钥匙
‘

=>

‘
价值
‘
,
4
]]);
返回（new UserCollection（User::all()->load（'roles'）））->additional（['meta' => ['key' =>'value'，]]）；

资源响应

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

1
使用
应用程序\Http\资源\
用户资源
;
2
使用
应用程序\模型\
用户
;
3
4
路线
::
得到
（
‘
/用户身份}
‘
,
功能

（
细绳

$id
）
{
5

返回

新的

用户资源
（
用户
::
查找或失败
（
$id
））；
6
});
使用 App\Http\Resources\UserResource；使用 App\Models\User；Route::get('/user/{id}'，函数（字符串 $id）{返回新的 UserResource（User::findOrFail($id)); });

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

1
使用
应用程序\Http\资源\
用户资源
;
2
使用
应用程序\模型\
用户
;
3
4
路线
::
得到
（
‘
/用户
‘
,
功能

（）
{
5

返回
（
新的

用户资源
（
用户
::
寻找
（
1
）））
6

->
回复
（）
7

->
标题
（
‘
X 值
‘
,
‘
真的
‘
（英文）：
8
});
使用 App\Http\Resources\UserResource；使用 App\Models\User；Route::get('/user'，函数 () {return (new UserResource(User::find(1))) ->response() ->header('X-Value'，'True'); });

或者，你可以定义一个 withResponse 资源本身内的方法。当资源作为响应中最外层的资源返回时，将调用此方法：

1
2
3
命名空间
应用程序\Http\资源；
4
5
使用
照亮\Http\
JsonResponse
;
6
使用
照亮\Http\
要求
;
7
使用
照亮\Http\Resources\Json\
Json资源
;
8
9
班级

用户资源

延伸

Json资源
10
{
11

/**
12
* 将资源转换为数组。
13
*
14
*
@返回

大批
<
细绳
, 混合>
15

*/
16

民众

功能

数组
（
要求

$请求
）
:

大批
17
{
18

返回
[
19

‘
ID
‘

=>

$this
->id
,
20
]；
21
}
22
23

/**
24
* 定制资源的传出响应。
25

*/
26

民众

功能

带有响应
（
要求

$请求
,
JsonResponse

$响应
）
:

空白
27
{
28

$响应
->
标题
（
‘
X 值
‘
,
‘
真的
‘
（英文）：
29
}
30
}
 */ public function toArray(Request $request): array { return [ 'id' => $this->id, ]; } /** * 自定义资源的传出响应。 */ public function withResponse(Request $request, JsonResponse $response): void { $response->header('X-Value', 'True'); } }

序幕

入门

架构概念

基础知识

深入挖掘

安全

数据库

Eloquent ORM

测试

套餐

Eloquent：API 资源

介绍

生成资源

资源集合

概念概述

资源集合

保存集合键

自定义底层资源类

写作资源

关系

资源集合

数据包装

包装嵌套资源

条件属性

合并条件属性

条件关系

有条件的关系很重要

条件枢轴信息

添加元数据

顶级元数据

构建资源时添加元数据

资源响应

本页内容

产品

套餐

资源

合作伙伴的优惠