> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Eloquent 序列化

> 介绍如何将 Eloquent 模型转换为 JSON 与数组，如何控制属性的显示与隐藏、设置附加属性以及自定义日期格式。

## 简介

在使用 Laravel 构建 API 时，经常需要把模型及其关联转换为数组或 JSON。
Eloquent 提供了便捷的方法来完成这些转换，并且可以控制序列化结果中包含哪些属性。

<Info>
  关于 Eloquent 模型和集合更稳健的 JSON 序列化方式，请参考 [Eloquent API 资源](./eloquent-resources) 文档。
</Info>

## 模型与数组

### 序列化为数组

要把模型及其已加载的[关联](./eloquent-relationships)转换为数组，使用 `toArray` 方法。
它是递归的，因此所有属性以及所有关联（包括关联中的关联）都会被转换为数组。

```php theme={null}
use App\Models\User;

$user = User::with('roles')->first();

return $user->toArray();
```

如果只想把模型自身的属性（不含关联）转换为数组，可以使用 `attributesToArray` 方法。

```php theme={null}
$user = User::first();

return $user->attributesToArray();
```

要把整个模型集合转换为数组，请调用集合实例的 `toArray` 方法。

```php theme={null}
$users = User::all();

return $users->toArray();
```

### 序列化为 JSON

要把模型转换为 JSON，使用 `toJson` 方法。
与 `toArray` 一样，`toJson` 也是递归的，所有属性和关联都会被转换为 JSON。
你还可以传入 [PHP 支持的 JSON 编码选项](https://secure.php.net/manual/en/function.json-encode.php)。

```php theme={null}
use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);
```

也可以把模型或集合强制转换为字符串，这时会自动调用 `toJson` 方法。

```php theme={null}
return (string) User::find(1);
```

由于模型和集合在被强制转为字符串时会变成 JSON，因此可以直接从路由或控制器返回 Eloquent 对象。
Laravel 会自动把从路由或控制器返回的 Eloquent 模型与集合序列化为 JSON。

```php theme={null}
Route::get('/users', function () {
    return User::all();
});
```

#### 关联

当 Eloquent 模型被转换为 JSON 时，已加载的关联会以 JSON 对象属性的形式自动包含进来。
另外，Eloquent 的关联方法名是“驼峰式”的，但关联的 JSON 属性会以“蛇形”命名。

## 控制属性的显示

### 隐藏属性

有时希望在模型的数组或 JSON 表示中隐藏诸如密码之类的属性。
这时可以在模型上使用 `Hidden` 属性。
被列在 `Hidden` 属性中的字段将不会出现在模型序列化后的结果中。

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Model;

#[Hidden(['password'])]
class User extends Model
{
    // ...
}
```

<Info>
  要隐藏关联，把关联的方法名加入到 Eloquent 模型的 Hidden 属性即可。
</Info>

### 显示属性

也可以使用 `Visible` 属性来定义一份“白名单”，只有其中列出的属性才会出现在数组和 JSON 表示中。
不在 `Visible` 属性列表中的属性在序列化时会被隐藏。

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Visible;
use Illuminate\Database\Eloquent\Model;

#[Visible(['first_name', 'last_name'])]
class User extends Model
{
    // ...
}
```

### 属性的临时显示 / 隐藏

如果需要在某个模型实例上临时显示原本被隐藏的属性，可以使用 `makeVisible` 或 `mergeVisible` 方法。
`makeVisible` 方法会返回模型实例。

```php theme={null}
return $user->makeVisible('attribute')->toArray();

return $user->mergeVisible(['name', 'email'])->toArray();
```

反之，如果要隐藏原本可见的属性，可以使用 `makeHidden` 或 `mergeHidden` 方法。

```php theme={null}
return $user->makeHidden('attribute')->toArray();

return $user->mergeHidden(['name', 'email'])->toArray();
```

若要一次性覆盖全部显示或隐藏属性，可以使用 `setVisible` 和 `setHidden` 方法。

```php theme={null}
return $user->setVisible(['id', 'name'])->toArray();

return $user->setHidden(['email', 'password', 'remember_token'])->toArray();
```

## 附加属性

在把模型转换为数组或 JSON 时，有时希望加入一些在数据库中并没有对应列的属性。
首先需要定义相应的[访问器](./eloquent-mutators)。

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 判断用户是否为管理员。
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}
```

如果希望始终把该访问器加入模型的数组和 JSON 表示，可以在模型上使用 `Appends` 属性。
访问器的 PHP 方法名是“驼峰式”，但属性名通常使用“蛇形”作为其序列化后的形式。

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Appends;
use Illuminate\Database\Eloquent\Model;

#[Appends(['is_admin'])]
class User extends Model
{
    // ...
}
```

属性被加入到 `appends` 列表后，会同时出现在模型的数组与 JSON 表示中。
`appends` 数组中的属性同样遵循模型的 `visible` 与 `hidden` 设置。

### 运行时追加

你可以在运行时通过 `append` 或 `mergeAppends` 方法要求模型实例追加额外属性。
也可以使用 `setAppends` 方法来覆盖特定模型实例的整个附加属性数组。

```php theme={null}
return $user->append('is_admin')->toArray();

return $user->mergeAppends(['is_admin', 'status'])->toArray();

return $user->setAppends(['is_admin'])->toArray();
```

若要移除模型上所有的追加属性，可以使用 `withoutAppends` 方法。

```php theme={null}
return $user->withoutAppends()->toArray();
```

## 日期的序列化

### 自定义默认日期格式

你可以通过重写 `serializeDate` 方法来自定义默认的序列化格式。
此方法不会影响写入数据库时的日期格式。

```php theme={null}
/**
 * 为数组 / JSON 序列化准备日期。
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}
```

### 每个属性的日期格式

也可以在模型的[类型转换声明](./eloquent-mutators#attribute-casting)中为单个日期属性指定序列化格式。

```php theme={null}
protected function casts(): array
{
    return [
        'birthday' => 'date:Y-m-d',
        'joined_at' => 'datetime:Y-m-d H:00',
    ];
}
```


## Related topics

- [Laravel 12 升级到 13 指南](/zh/blog/upgrade-12-to-13.md)
- [Redis](/zh/redis.md)
- [Laravel 13 新功能汇总](/zh/blog/laravel-13-new-features.md)
- [进程](/zh/processes.md)
- [Eloquent 集合](/zh/eloquent-collections.md)