后盾人

Eloquent ORM

Laravel 5.7 中文文档 / 序列化

# Eloquent: 序列化

## 介绍

构建JSON API时，通常需要将模型和关系转换为数组或JSON。Eloquent包括用于进行这些转换的便捷方法，以及控制序列化中包含哪些属性。

## 序列化模型和集合

### 序列化到数组

要将模型及其加载的[关系](https://laravel.com/docs/5.7/eloquent-relationships)转换为数组，您应该使用该`toArray`方法。此方法是递归的，因此所有属性和所有关系（包括关系关系）都将转换为数组：

```php
$user = App\User::with('roles')->first();

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

您还可以将整个模型[集合](https://laravel.com/docs/5.7/eloquent-collections)转换为数组：

```php
$users = App\User::all();

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

### 序列化为JSON

要将模型转换为JSON，您应该使用该`toJson`方法。比如`toArray`，该`toJson`方法是递归的，因此所有属性和关系都将转换为JSON。您还可以指定[PHP支持的](http://php.net/manual/en/function.json-encode.php) JSON编码选项：

```php
$user = App\User::find(1);

return $user->toJson();

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

或者，您可以将模型或集合强制转换为字符串，该字符串将自动调用`toJson`模型或集合上的方法：

```php
$user = App\User::find(1);

return (string) $user;
```

由于模型和集合在转换为字符串时会转换为JSON，因此您可以直接从应用程序的路径或控制器返回Eloquent对象：

```php
Route::get('users', function () {
    return App\User::all();
});
```

## 隐藏JSON的属性

有时，您可能希望限制模型数组或JSON表示中包含的属性（如密码）。为此，请`$hidden`向模型添加属性：

```php
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The attributes that should be hidden for arrays.
     *
     * @var array
     */
    protected $hidden = ['password'];
}
```

> 隐藏关系时，请使用关系的方法名称。

或者，您可以使用该`visible`属性来定义应包含在模型的数组和JSON表示中的属性的白名单。将模型转换为数组或JSON时，将隐藏所有其他属性：

```php
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The attributes that should be visible in arrays.
     *
     * @var array
     */
    protected $visible = ['first_name', 'last_name'];
}
```

#### 暂时修改属性可见性

如果您想在给定的模型实例上显示一些通常隐藏的属性，则可以使用该`makeVisible`方法。该`makeVisible`方法返回模型实例以方便方法链接：

```php
return $user->makeVisible('attribute')->toArray();
```

同样，如果您想在给定的模型实例上隐藏一些通常可见的属性，您可以使用该`makeHidden`方法。

```php
return $user->makeHidden('attribute')->toArray();
```

## 将值附加到JSON

有时，在将模型转换为数组或JSON时，您可能希望添加数据库中没有相应列的属性。为此，首先为值定义一个[访问器](https://laravel.com/docs/5.7/eloquent-mutators)：

```php
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Get the administrator flag for the user.
     *
     * @return bool
     */
    public function getIsAdminAttribute()
    {
        return $this->attributes['admin'] == 'yes';
    }
}
```

创建访问者后，将属性名称添加到`appends`模型的属性中。请注意，属性名称通常在“snake case”中引用，即使访问者是使用“camel case”定义的：

```php
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The accessors to append to the model's array form.
     *
     * @var array
     */
    protected $appends = ['is_admin'];
}
```

将属性添加到`appends`列表后，它将包含在模型的数组和JSON表示中。中的属性`appends`阵列也将尊重`visible`和`hidden`在模型上配置的设置。

#### 在运行时附加

您可以指示单个模型实例使用该`append`方法追加属性。或者，您可以使用该`setAppends`方法覆盖给定模型实例的整个附加属性数组：

```php
return $user->append('is_admin')->toArray();

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

## 日期序列化

#### 自定义每个属性的日期格式

您可以通过在[cast声明中](https://laravel.com/docs/5.7/eloquent-mutators#attribute-casting)指定日期格式来自定义各个Eloquent日期属性的序列化格式：

```php
protected $casts = [
    'birthday' => 'date:Y-m-d',
    'joined_at' => 'datetime:Y-m-d H:00',
];
```

#### Carbon 全局自定义

Laravel 扩展了[Carbon](https://github.com/briannesbitt/Carbon)日期库，这为 Carbon 的 JSON 序列化提供了便利。要自定义所有 Carbon 日期在整个应用中的序列化，可以使用 `Carbon::serializeUsing` 方法。方法 `serializeUsing` 接受一个闭包，该闭包返回一个字符串形式的日期。

```php
<?php

namespace App\Providers;

use Illuminate\Support\Carbon;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Perform post-registration booting of services.
     *
     * @return void
     */
    public function boot()
    {
        Carbon::serializeUsing(function ($carbon) {
            return $carbon->format('U');
        });
    }

/**
     * Register bindings in the container.
     *
     * @return void
     */
    public function register()
    {
        //
    }
}
```