Laravel模型数组序列化？数组形式怎样转换？

月夜之吻

发布时间：2025-09-17 09:58:01

266人浏览过

来源于php中文网

原创

Laravel模型转换为数组的核心是toArray()方法，它可将模型实例或集合转为数组，支持可见性控制（$visible/$hidden）、动态字段调整（makeVisible/makeHidden）、自定义属性添加（$appends结合访问器），并自动处理日期、类型转换及关联关系；集合的toArray()会遍历每个模型调用其toArray()，结构为索引数组嵌套关联数组，且在JSON响应中自动触发序列化，提升API开发效率。

laravel模型数组序列化？数组形式怎样转换？

Laravel模型要序列化成数组形式，或者说将模型数据转换为数组，其实在框架里是相当直观且灵活的。最核心的方法就是调用模型实例或模型集合上的

toArray()

方法。它会把模型的所有属性（根据可见性设置）以及任何通过

appends

添加的自定义属性，都规整地转换成一个关联数组，方便你进行后续的数据处理或者API响应。

解决方案

当我们谈论Laravel模型如何转换成数组形式，核心其实是围绕着

toArray()

这个方法展开的。无论是单个模型实例，还是一个模型集合（

Collection

），你都可以直接调用它。

对于一个单独的模型实例，比如你从数据库里取出来一个

User

对象：

$user = App\Models\User::find(1);
$userArray = $user->toArray();

// $userArray 现在就是一个包含用户所有可见属性的关联数组
// 例如：['id' => 1, 'name' => 'John Doe', 'email' => 'john@example.com', ...]

如果你有一个模型集合，比如查询结果返回了多个用户：

$users = App\Models\User::all();
$usersArray = $users->toArray();

// $usersArray 会是一个包含多个用户数组的数组
// 例如：[
//     ['id' => 1, 'name' => 'John Doe', ...],
//     ['id' => 2, 'name' => 'Jane Smith', ...],
// ]

这里值得一提的是，

toArray()

在模型集合上调用时，它会遍历集合中的每一个模型，并对每个模型都调用其自身的

toArray()

方法。这保证了无论你处理的是单个模型还是多个模型，其内部的序列化逻辑都是一致的。

此外，Laravel模型还实现了

JsonSerializable

接口，这意味着当你直接将一个模型或模型集合

json_encode()

的时候，它会自动调用

toArray()

方法。所以，很多时候你甚至不需要显式地去调用

toArray()

，比如在返回API响应时：

return App\Models\User::find(1); // Laravel会自动将其序列化为JSON

这背后的逻辑是，框架会先将模型隐式地转换为数组，再将数组转换为JSON字符串。这种设计，我觉得是Laravel在开发者体验上做得非常棒的一点，省去了很多繁琐的步骤。

如何精确控制Laravel模型转换为数组时包含的字段？

在实际开发中，我们很少需要将模型的所有字段都暴露出去，特别是涉及到敏感信息时。精确控制哪些字段被序列化，哪些被隐藏，是API设计和安全性的重要一环。Laravel提供了几种非常灵活的机制来处理这个问题。

最常用的，也是最基础的方法，是使用模型上的

$visible

和

$hidden

属性。

```
$visible
```
属性：如果你只希望模型数组中包含特定字段，你可以定义
```
$visible
```
数组。模型在转换为数组时，只会包含
```
$visible
```
中列出的字段。
```
class User extends Model
{
    protected $visible = ['id', 'name', 'email'];
}
```
这样，即使数据库里有
```
password
```
字段，调用
```
$user->toArray()
```
也不会包含它。
```
$hidden
```
属性：与
```
$visible
```
相反，
```
$hidden
```
属性定义了在模型序列化为数组时应该被隐藏的字段。这是我个人更倾向于使用的方式，因为它允许你默认暴露所有字段，只针对性地隐藏少数敏感字段。
```
class User extends Model
{
    protected $hidden = ['password', 'remember_token'];
}
```
这样，
```
password
```
和
```
remember_token
```
字段就不会出现在数组中了。

这两种方法是定义在模型类上的，意味着它们是全局性的默认行为。但很多时候，你可能需要在不同的场景下有不同的可见性需求。比如，在用户个人资料页需要显示某个字段，但在公开的用户列表中又需要隐藏。这时，你就可以利用模型实例的动态方法：

```
makeVisible(array $attributes)
```
：临时让某些被
```
$hidden
```
的字段可见。
```
makeHidden(array $attributes)
```
：临时隐藏某些被
```
$visible
```
或默认可见的字段。

易通cmseasy免费的企业建站程序2.0 UTF-8 build 201000510 中文版
易通(企业网站管理系统)是一款小巧,高效,人性化的企业建站程序.易通企业网站程序是国内首款免费提供模板的企业网站系统.§ 简约的界面及小巧的体积：后台菜单完全可以修改成自己最需要最高效的形式；大部分操作都集中在下拉列表框中，以节省更多版面来显示更有价值的数据；数据的显示以Javascript数组类型来输出，减少数据的传输量，加快传输速度。 § 灵活的模板标签及模

下载
```
$user = App\Models\User::find(1);

// 假设password在$hidden中
$userWithPassword = $user->makeVisible(['password'])->toArray();
// 此时$userWithPassword会包含password字段

// 假设email默认可见
$userWithoutEmail = $user->makeHidden(['email'])->toArray();
// 此时$userWithoutEmail不会包含email字段
```
这种链式调用的方式非常方便，你可以在控制器或服务层根据具体业务逻辑动态调整字段的可见性，而不会影响模型本身的定义。

当然，如果你的序列化需求变得非常复杂，比如需要嵌套资源、转换字段名、进行复杂的权限判断等等，那么Laravel的API资源（API Resources）会是更好的选择。它提供了一个更强大的抽象层，让你能以更声明式的方式来定义JSON响应的结构。虽然超出了“模型数组序列化”的直接范畴，但它确实是处理复杂序列化场景的终极武器。我通常会把API资源看作是模型

toArray()

的一个高级、结构化的替代方案。

Laravel模型如何添加自定义属性到序列化数组中？

有时候，我们希望在模型转换为数组时，能够包含一些并非直接存储在数据库中的属性。这些属性可能是通过计算得出的，或者是通过与其他模型关联得来的，但我们希望它们能像普通字段一样出现在最终的数组中。Laravel提供了“访问器”（Accessors）和

$appends

属性来优雅地解决这个问题。

首先，你需要为你的自定义属性创建一个访问器（Accessor）。访问器本质上是一个方法，它的命名遵循

get{AttributeName}Attribute

的格式。例如，如果你想添加一个

full_name

属性，你可以这样做：

class User extends Model
{
    // ... 其他模型定义

    public function getFullNameAttribute()
    {
        return $this->first_name . ' ' . $this->last_name;
    }
}

现在，你就可以像访问普通属性一样访问

full_name

了：

$user->full_name

。

然而，仅仅定义访问器并不会让

full_name

自动出现在

$user->toArray()

的结果中。为了让它包含在序列化数组里，你需要将这个自定义属性添加到模型的

$appends

属性数组中：

class User extends Model
{
    protected $appends = ['full_name'];

    public function getFullNameAttribute()
    {
        return $this->first_name . ' ' . $this->last_name;
    }
}

一旦你这样做了，当你调用

$user->toArray()

时，

full_name

就会作为一个新的键值对出现在结果数组中，就像它是一个真实的数据库字段一样。

这种机制的强大之处在于，它让你的模型数据更加丰富和完整，而无需修改数据库结构。我个人经常用它来处理一些聚合数据，比如一个

Order

模型可能有一个

total_amount

访问器，它会计算所有订单项的总和，然后我将其

$appends

到订单模型中，这样在API响应时就能直接拿到总金额，非常方便。

需要注意的是，

$appends

中的属性名必须与你的访问器方法名（去掉

get

和

Attribute

，并转换为蛇形命名）相匹配。如果你的访问器需要额外的参数，或者逻辑非常复杂，超出了单个方法能承载的范围，那可能就需要重新审视设计，或者考虑使用API资源来封装这些复杂逻辑了。保持

$appends

的属性简洁明了，通常是更好的实践。

在Laravel中，集合（Collection）与单个模型（Model）的数组序列化有何不同？

从表面上看，无论是单个模型还是模型集合，我们都可以调用

toArray()

方法，并且它们都能得到预期的数组结果。但它们内部的工作机制，以及在处理上的细微差别，还是值得我们深入理解一下的。

单个模型的

toArray()

：当你对一个

App\Models\Model

实例调用

toArray()

时，它会执行以下步骤：

处理可见性/隐藏性： 根据
```
$visible
```
和
```
$hidden
```
属性，过滤掉不需要的字段。
处理日期字段： 将日期字段（如
```
created_at
```
,
```
updated_at
```
等，以及
```
$dates
```
属性中定义的字段）根据
```
$dateFormat
```
或默认格式转换为字符串。
处理类型转换（Casts）： 应用
```
$casts
```
属性中定义的类型转换，比如将JSON字符串转换为PHP数组，或将布尔值转换为实际的布尔类型。
处理追加属性（Appends）： 遍历
```
$appends
```
数组，为每个追加属性调用对应的访问器，并将返回值添加到结果数组中。
处理关系： 如果模型加载了关联关系（通过
```
with()
```
或惰性加载），并且这些关系没有被
```
$hidden
```
，那么关联的模型也会被递归地调用
```
toArray()
```
，并作为嵌套数组添加到当前模型的数组中。

这个过程是针对单个模型实例的，它确保了每个模型都能根据其自身的定义，被精确地转换为一个独立的关联数组。

模型集合的

toArray()

：当你对一个

Illuminate\Database\Eloquent\Collection

实例调用

toArray()

时，它的行为就有点不同了。它并不会直接处理集合本身的数据，而是：

迭代集合：
```
Collection->toArray()
```
会遍历集合中的每一个模型实例。
调用模型
toArray()
：对集合中的每一个模型实例，它都会调用该模型自身的
```
toArray()
```
方法。
聚合结果： 将每个模型
```
toArray()
```
返回的关联数组，收集到一个新的索引数组中。

所以，最终你得到的是一个包含多个关联数组的索引数组，每个关联数组都代表了集合中的一个模型。

核心差异点和考量：

递归性： 单个模型的
```
toArray()
```
是递归的，它会处理加载的关联关系。集合的
```
toArray()
```
也是“递归”的，因为它对集合中的每个元素都执行了
```
toArray()
```
，从而间接处理了每个模型及其关联关系。
结构： 单个模型得到的是一个关联数组。集合得到的是一个索引数组，其中每个元素都是一个关联数组。
性能： 对于大型集合，
```
Collection->toArray()
```
会对每个模型执行上述所有步骤，这可能会有性能开销。如果你只需要集合中某些模型的特定字段，或者想进行更复杂的聚合，使用
```
map()
```
或
```
pluck()
```
等集合方法可能更高效。例如，
```
$users->map(fn($user) => ['id' => $user->id, 'name' => $user->name])->toArray()
```
就能避免不必要的字段序列化。
JSON序列化： 如前所述，无论是模型还是集合，当你将它们直接返回为API响应或
```
json_encode()
```
时，Laravel都会自动调用
```
toArray()
```
。这让开发体验非常流畅，你通常不需要手动去区分处理。