访问器和修改器

简介

访问器和修改器允许你在获取模型属性或设置其值时格式化 Eloquent 属性。例如，你可能想要使用 Laravel 加密器对存储在数据库中的数据进行加密，并且在 Eloquent 模型中访问时自动进行解密。

除了自定义访问器和修改器，Eloquent 还可以自动转换日期字段为 Carbon 实例甚至将文本转换为JSON。

访问器 & 修改器

定义访问器

要定义一个访问器，需要在模型中创建一个 getFooAttribute 方法，其中 Foo 是你想要访问的字段名（使用驼峰式命名规则）。在本例中，我们将会为 first_name 属性定义一个访问器，该访问器在获取 first_name 的值时被 Eloquent 自动调用：

<?php
    
namespace App\Models;
    
use Illuminate\Database\Eloquent\Model;
    
class User extends Model
{
    /**
     * 获取用户的名字
     *
     * @param  string  $value
     * @return string
     */
    public function getFirstNameAttribute($value)
    {
        return ucfirst($value);
    }
}

正如你所看到的，该字段的原生值被传递给访问器，然后返回处理过的值。要访问该值只需要简单访问 first_name 即可：

$user = App\Models\User::find(1);
$firstName = $user->first_name;

当然，你也可以使用访问器将已存在的属性转化为全新的、经过处理的值：

/**
 * 获取用户的全名
 *
 * @return string
 */
public function getFullNameAttribute()
{
    return "{$this->first_name} {$this->last_name}";
}

注：如果你想要把这些计算值添加到以数组/JSON格式表示的模型，需要手动追加它们。

定义修改器

要定义一个修改器，需要在模型中定义 setFooAttribute 方法，其中 Foo 是你想要访问的字段（使用驼峰式命名规则）。接下来让我们为 first_name 属性定义一个修改器，当我们为模型上的 first_name 赋值时该修改器会被自动调用：

<?php
    
namespace App\Models;
    
use Illuminate\Database\Eloquent\Model;
    
class User extends Model
{
    /**
     * 设置用户的名字
     *
     * @param  string  $value
     * @return string
     */
    public function setFirstNameAttribute($value)
    {
        $this->attributes['first_name'] = strtolower($value);
    }
}

该修改器获取要被设置的属性值，允许你操纵该值并设置 Eloquent 模型内部属性值为操作后的值。例如，如果你尝试设置 Sally 的 first_name 属性：

$user = App\Models\User::find(1);
$user->first_name = 'Sally';

在本例中，setFirstNameAttribute 方法会被调用，传入参数为 Sally，修改器会对其调用 strtolower 函数并将处理后的值设置为内部属性的值。

日期修改器

默认情况下，Eloquent 将会转化 created_at 和 updated_at 列的值为 Carbon 实例，该类继承自 PHP 原生的 Datetime 类，并提供了各种有用的方法。你可以自定义哪些字段被自动调整修改，甚至可以通过重写模型中的 $dates 属性完全禁止调整：

<?php
    
namespace App\Models;
    
use Illuminate\Database\Eloquent\Model;
    
class User extends Model
{
    /**
     * 应该被调整为日期的属性
     *
     * @var array
     */
    protected $dates = [
        'seen_at'
    ];
}

注：你可以通过设置模型的公共属性 $timestamps 值为 false 来禁止默认的 created_at 和 updated_at 时间戳。

如果字段是日期格式时，你可以将其值设置为 UNIX 时间戳，日期字符串（Y-m-d），日期-时间字符串，Datetime/Carbon 实例，日期的值将会自动以正确格式存储到数据库中：

$user = App\Models\User::find(1);
$user->disabled_at = Carbon::now();
$user->save();

正如上面提到的，当获取被罗列在 $dates 数组中的属性时，它们会被自动转化为 Carbon 实例，并允许你在属性上使用任何 Carbon 类的方法：

$user = App\Models\User::find(1);
return $user->disabled_at->getTimestamp();

日期格式化

默认情况下，时间戳的格式是 'Y-m-d H:i:s'，如果你需要自定义时间戳格式，在模型中设置 $dateFormat 属性，该属性决定日期属性存储在数据库以及序列化为数组或 JSON 时的格式：

<?php
    
namespace App\Models;
    
use Illuminate\Database\Eloquent\Model;
    
class Flight extends Model
{
    /**
     * 模型日期的存储格式
     *
     * @var string
     */
    protected $dateFormat = 'U';
}

属性转换

模型中的 $casts 属性为属性字段转换到通用数据类型提供了便利方法 。$casts 属性是数组格式，其键是要被转换的属性名称，其值时你想要转换的类型。目前支持的转换类型包括：integer, real, float, double, decimal:<digits>, string, boolean, object，array，collection，date，datetime 和 timestamp。转化为 decimal 时，必须定义数字的位数（decimal:2）。

例如，让我们转换 is_admin 属性，将其由 integer 值（0或1）转换为 boolean 值：

<?php
    
namespace App\Models;
    
use Illuminate\Database\Eloquent\Model;
    
class User extends Model
{
    /**
     * 应该被转化为原生类型的属性
     *
     * @var array
     */
    protected $casts = [
        'is_admin' => 'boolean',
    ];
}

现在，is_admin 属性在被访问时总是被转换为 boolean，即使底层存储在数据库中的值是 integer：

$user = App\Models\User::find(1);
    
if ($user->is_admin) {
    //
}

注：值为 null 的属性不会被转化，此外，不要定义和关联关系同名的转化（或者属性）。

自定义转化

Laravel 提供了多种内置的、有用的转化类型，不过，有时候你可能需要自定义自己的类型，这可以通过定义一个实现 CastsAttributes 接口的类来完成。

实现该接口的类必须定义 get 和 set 方法，get 方法负责将数据库原生值转化为转化值，而 set 方法会将转化值转化为可以存储到数据库的值。例如，我们通过自定义转化类型来重新实现内置的 json 转化类型：

<?php

namespace App\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;

class Json implements CastsAttributes
{
    /**
     * 转化给定值
     *
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @param  string  $key
     * @param  mixed  $value
     * @param  array  $attributes
     * @return array
     */
    public function get($model, $key, $value, $attributes)
    {
        return json_decode($value, true);
    }

    /**
     * 准备用于存储到数据库的值
     *
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @param  string  $key
     * @param  array  $value
     * @param  array  $attributes
     * @return string
     */
    public function set($model, $key, $value, $attributes)
    {
        return json_encode($value);
    }
}

定义好自定义转化类型后，可以通过类名将其应用到模型属性使其生效：

<?php

namespace App\Models;

use App\Casts\Json;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 需要被转化的属性
     *
     * @var array
     */
    protected $casts = [
        'options' => Json::class,
    ];
}

值对象转化

你可以将值转化为原生类型，也可以将其转化为对象。定义值与对象的自定义转化和原生类型类似，不过，set 方法这个时候应该返回键值对数组，用于定义存储到数据库的字段与值的映射关系。

举个例子，我们来定义一个自定义的转化类，将多个模型属性值转化为单个 Address 值对象，假设 Address 值有两个公共属性 —— lineOne 和 lineTwo：

<?php

namespace App\Casts;

use App\Models\Address as AddressModel;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use InvalidArgumentException;

class Address implements CastsAttributes
{
    /**
     * 转化给定值对 Address 对象
     *
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @param  string  $key
     * @param  mixed  $value
     * @param  array  $attributes
     * @return \App\Models\Address
     */
    public function get($model, $key, $value, $attributes)
    {
        return new AddressModel(
            $attributes['address_line_one'],
            $attributes['address_line_two']
        );
    }

    /**
     * 将对象转化为存储到数据库的原始值
     *
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @param  string  $key
     * @param  \App\Models\Address  $value
     * @param  array  $attributes
     * @return array
     */
    public function set($model, $key, $value, $attributes)
    {
        if (! $value instanceof AddressModel) {
            throw new InvalidArgumentException('The given value is not an Address instance.');
        }
        
        return [
            'address_line_one' => $value->lineOne,
            'address_line_two' => $value->lineTwo,
        ];
    }
}

当转化为值对象时，任何对值对象的修改都会在模型保存之前自动同步到模型实例：

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

$user->address->lineOne = 'Updated Address Value';

$user->save();

注：如果你想要将包含值对象的 Eloquent 模型序列化为 JSON 或者数组，需要在值对象上实现 Illuminate\Contracts\Support\Arrayable 和 JsonSerializable 接口。

写入转化

有时候，你可能需要编写一个这样的自定义转化：只有在保存模型到数据库时才应用类型转化，从数据库初始化模型实例时不做任何操作，我们姑且将其称作「写入转化」。一个典型的写入转化例子就是「哈希」转化，自定义的写入转化类需要实现 CastsInboundAttributes 接口，并且只需要实现 set 方法即可：

<?php

namespace App\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsInboundAttributes;

class Hash implements CastsInboundAttributes
{
    /**
     * The hashing algorithm.
     *
     * @var string
     */
    protected $algorithm;

    /**
     * Create a new cast class instance.
     *
     * @param  string|null  $algorithm
     * @return void
     */
    public function __construct($algorithm = null)
    {
        $this->algorithm = $algorithm;
    }

    /**
     * Prepare the given value for storage.
     *
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @param  string  $key
     * @param  array  $value
     * @param  array  $attributes
     * @return string
     */
    public function set($model, $key, $value, $attributes)
    {
        return is_null($this->algorithm)
                    ? bcrypt($value);
                    : hash($this->algorithm, $value);
    }
}

转化参数

当应用自定以转化到模型时，转化参数可以通过形如「类名 + "." + 参数值」的约定方式传入，如果有多个参数的话，在参数值中都过 , 分隔。这些参数值都会被传入转化类的构造函数：

/**
 * The attributes that should be cast.
 *
 * @var array
 */
protected $casts = [
    'secret' => Hash::class.':sha256',
];

可转化类

除了添加自定义属性转化到模型类之外，还可以添加一个实现 Illuminate\Contracts\Database\Eloquent\Castable 接口的可转化类：

protected $casts = [
    'address' => \App\Models\Address::class,
];

实现 Castable 接口的对象必须定义 castUsing 方法，该方法会返回自定义转化器的类名，我们可以在这个转化器类中定义具体的转换逻辑：

<?php

namespace App\Models;

use Illuminate\Contracts\Database\Eloquent\Castable;
use App\Casts\Address as AddressCast;

class Address implements Castable
{
    /**
     * Get the name of the caster class to use when casting from / to this cast target.
     *
     * @return string
     */
    public static function castUsing()
    {
        return AddressCast::class;
    }
}

使用 Castable 类时，我们仍然可以传递参数给 $casts 定义，这些参数会直接传递给转化器类：

protected $casts = [
    'address' => \App\Models\Address::class.':argument',
];

数组 & JSON 转换

array 类型转换在处理被存储为序列化 JSON 格式的字段时特别有用，例如，如果数据库有一个 JSON 或 TEXT 字段类型包含了序列化 JSON，添加 array 类型转换到该属性将会在 Eloquent 模型中访问其值时自动将其反序列化为 PHP 数组：

<?php
    
namespace App\Models;
    
use Illuminate\Database\Eloquent\Model;
    
class User extends Model
{
    /**
     * 应该被转化为原生类型的属性
     *
     * @var array
     */
    protected $casts = [
        'options' => 'array',
    ];
}

类型转换被定义后，访问 options 属性将会自动从 JSON 反序列化为 PHP 数组，反之，当你设置 options 属性的值时，给定数组将会自动转化为 JSON 以供存储：

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

$options = $user->options;

$options['key'] = 'value';

$user->options = $options;

$user->save();

要通过更简练的语法更新 JSON 属性的单个字段，可以使用 -> 操作符：

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

$user->update(['options->key' => 'value']);

日期转换

当使用 date 或 datetime 转换类型时，可以指定日期的格式，这个格式会在模型序列化为数组或 JSON 时使用：

/**
 * The attributes that should be cast to native types.
 *
 * @var array
 */
protected $casts = [
    'created_at' => 'datetime:Y-m-d',
];

查询期间时间转化

有时候，你可能需要在执行数据库操作时应用类型转化，比如从数据表获取原始值时。考虑下面这个示例：

use App\Models\Post;
use App\Models\User;

$users = User::select([
    'users.*',
    'last_posted_at' => Post::selectRaw('MAX(created_at)')
            ->whereColumn('user_id', 'users.id')
])->get();

查询结果集的 last_posted_at 属性值时一个原始字符串，如果能在执行查询时在该属性上应用 date 类型转化将会非常方便。要实现这个功能，可以使用 withCasts 方法：

$users = User::select([
    'users.*',
    'last_posted_at' => Post::selectRaw('MAX(created_at)')
            ->whereColumn('user_id', 'users.id')
])->withCasts([
    'last_posted_at' => 'date'
])->get();