Laravel模型转换为数组的核心是toArray()方法，它可将模型实例或集合转为数组，支持可见性控制（$visible/$hidden）、动态字段调整（makeVisible/makeHidden）、自定义属性添加（$appends结合访问器），并自动处理日期、类型转换及关联关系；集合的toArray()会遍历每个模型调用其toArray()，结构为索引数组嵌套关联数组，且在JSON响应中自动触发序列化，提升API开发效率。
Laravel模型要序列化成数组形式，或者说将模型数据转换为数组，其实在框架里是相当直观且灵活的。最核心的方法就是调用模型实例或模型集合上的
toArray()
方法。它会把模型的所有属性（根据可见性设置）以及任何通过
appends
添加的自定义属性，都规整地转换成一个关联数组，方便你进行后续的数据处理或者API响应。
解决方案
当我们谈论Laravel模型如何转换成数组形式，核心其实是围绕着
toArray()
这个方法展开的。无论是单个模型实例，还是一个模型集合（
Collection
），你都可以直接调用它。
对于一个单独的模型实例，比如你从数据库里取出来一个
User
对象：
$user = AppModelsUser::find(1); $userArray = $user->toArray(); // $userArray 现在就是一个包含用户所有可见属性的关联数组 // 例如：['id' => 1, 'name' => 'John Doe', 'email' => 'john@example.com', ...]
如果你有一个模型集合，比如查询结果返回了多个用户：
$users = AppModelsUser::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 AppModelsUser::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
或默认可见的字段。
$user = AppModelsUser::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()
： 当你对一个
AppModelsModel
实例调用
toArray()
时，它会执行以下步骤：
- 处理可见性/隐藏性： 根据
$visible
和
$hidden
属性，过滤掉不需要的字段。
- 处理日期字段： 将日期字段（如
created_at
,
updated_at
等，以及
$dates
属性中定义的字段）根据
$dateFormat
或默认格式转换为字符串。
- 处理类型转换（Casts）： 应用
$casts
属性中定义的类型转换，比如将JSON字符串转换为PHP数组，或将布尔值转换为实际的布尔类型。
- 处理追加属性（Appends）： 遍历
$appends
数组，为每个追加属性调用对应的访问器，并将返回值添加到结果数组中。
- 处理关系： 如果模型加载了关联关系（通过
with()
或惰性加载），并且这些关系没有被
$hidden
，那么关联的模型也会被递归地调用
toArray()
，并作为嵌套数组添加到当前模型的数组中。
这个过程是针对单个模型实例的，它确保了每个模型都能根据其自身的定义，被精确地转换为一个独立的关联数组。
模型集合的
toArray()
： 当你对一个
IlluminateDatabaseEloquentCollection
实例调用
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()
。这让开发体验非常流畅，你通常不需要手动去区分处理。
理解这些差异，能帮助我们更好地优化数据处理流程，尤其是在构建高性能API时，知道何时使用
toArray()
，何时使用更精细的集合操作，或者何时转向API资源，是至关重要的。
以上就是Laravel模型数组序列化？数组形式怎样转换？的详细内容，更多请关注laravel php word js json app access ai 键值对 php laravel json Array 关联数组 封装 字符串 递归 接口 布尔类型 Attribute Accessors 访问器 Collection map 类型转换 对象 database 数据库