Eloquent: Mutators

Introduction
Accessors & Mutators
- Defining An Accessor
- Defining A Mutator
Date Mutators
Attribute Casting

Introduction

Accessors and mutators allow you to format Eloquent attribute values when you retrieve or set them on model instances. For example, you may want to use the Laravel encrypter to encrypt a value while it is stored in the database, and then automatically decrypt the attribute when you access it on an Eloquent model.

In addition to custom accessors and mutators, Eloquent can also automatically cast date fields to Carbon instances or even cast text fields to JSON.

Accessors & Mutators

Defining An Accessor

To define an accessor, create a getFooAttribute method on your model where Foo is the "studly" cased name of the column you wish to access. In this example, we'll define an accessor for the first_name attribute. The accessor will automatically be called by Eloquent when attempting to retrieve the value of the first_name attribute:

 1<?php
 2 
 3namespace App;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class User extends Model
 8{
 9    /**
10     * Get the user's first name.
11     *
12     * @param  string  $value
13     * @return string
14     */
15    public function getFirstNameAttribute($value)
16    {
17        return ucfirst($value);
18    }
19}

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Get the user's first name.
     *
     * @param  string  $value
     * @return string
     */
    public function getFirstNameAttribute($value)
    {
        return ucfirst($value);
    }
}

As you can see, the original value of the column is passed to the accessor, allowing you to manipulate and return the value. To access the value of the accessor, you may access the first_name attribute on a model instance:

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

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

$firstName = $user->first_name;

You may also use accessors to return new, computed values from existing attributes:

1/**
2 * Get the user's full name.
3 *
4 * @return string
5 */
6public function getFullNameAttribute()
7{
8    return "{$this->first_name} {$this->last_name}";
9}

/**
 * Get the user's full name.
 *
 * @return string
 */
public function getFullNameAttribute()
{
    return "{$this->first_name} {$this->last_name}";
}

If you would like these computed values to be added to the array / JSON representations of your model, you will need to append them.

Defining A Mutator

To define a mutator, define a setFooAttribute method on your model where Foo is the "studly" cased name of the column you wish to access. So, again, let's define a mutator for the first_name attribute. This mutator will be automatically called when we attempt to set the value of the first_name attribute on the model:

 1<?php
 2 
 3namespace App;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class User extends Model
 8{
 9    /**
10     * Set the user's first name.
11     *
12     * @param  string  $value
13     * @return void
14     */
15    public function setFirstNameAttribute($value)
16    {
17        $this->attributes['first_name'] = strtolower($value);
18    }
19}

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Set the user's first name.
     *
     * @param  string  $value
     * @return void
     */
    public function setFirstNameAttribute($value)
    {
        $this->attributes['first_name'] = strtolower($value);
    }
}

The mutator will receive the value that is being set on the attribute, allowing you to manipulate the value and set the manipulated value on the Eloquent model's internal $attributes property. So, for example, if we attempt to set the first_name attribute to Sally:

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

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

$user->first_name = 'Sally';

In this example, the setFirstNameAttribute function will be called with the value Sally. The mutator will then apply the strtolower function to the name and set its resulting value in the internal $attributes array.

Date Mutators

By default, Eloquent will convert the created_at and updated_at columns to instances of Carbon, which extends the PHP DateTime class and provides an assortment of helpful methods. You may add additional date attributes by setting the $dates property of your model:

 1<?php
 2 
 3namespace App;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class User extends Model
 8{
 9    /**
10     * The attributes that should be mutated to dates.
11     *
12     * @var array
13     */
14    protected $dates = [
15        'seen_at',
16    ];
17}

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The attributes that should be mutated to dates.
     *
     * @var array
     */
    protected $dates = [
        'seen_at',
    ];
}

You may disable the default created_at and updated_at timestamps by setting the public $timestamps property of your model to false.

When a column is considered a date, you may set its value to a UNIX timestamp, date string (Y-m-d), date-time string, or a DateTime / Carbon instance. The date's value will be correctly converted and stored in your database:

1$user = App\User::find(1);
2 
3$user->deleted_at = now();
4 
5$user->save();

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

$user->deleted_at = now();

$user->save();

As noted above, when retrieving attributes that are listed in your $dates property, they will automatically be cast to Carbon instances, allowing you to use any of Carbon's methods on your attributes:

1$user = App\User::find(1);
2 
3return $user->deleted_at->getTimestamp();

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

return $user->deleted_at->getTimestamp();

Date Formats

By default, timestamps are formatted as 'Y-m-d H:i:s'. If you need to customize the timestamp format, set the $dateFormat property on your model. This property determines how date attributes are stored in the database:

 1<?php
 2 
 3namespace App;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Flight extends Model
 8{
 9    /**
10     * The storage format of the model's date columns.
11     *
12     * @var string
13     */
14    protected $dateFormat = 'U';
15}

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * The storage format of the model's date columns.
     *
     * @var string
     */
    protected $dateFormat = 'U';
}

Attribute Casting

The $casts property on your model provides a convenient method of converting attributes to common data types. The $casts property should be an array where the key is the name of the attribute being cast and the value is the type you wish to cast the column to. The supported cast types are: integer, real, float, double, decimal:<digits>, string, boolean, object, array, collection, date, datetime, and timestamp. When casting to decimal, you must define the number of digits (decimal:2).

To demonstrate attribute casting, let's cast the is_admin attribute, which is stored in our database as an integer (0 or 1) to a boolean value:

 1<?php
 2 
 3namespace App;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class User extends Model
 8{
 9    /**
10     * The attributes that should be cast.
11     *
12     * @var array
13     */
14    protected $casts = [
15        'is_admin' => 'boolean',
16    ];
17}

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The attributes that should be cast.
     *
     * @var array
     */
    protected $casts = [
        'is_admin' => 'boolean',
    ];
}

Now the is_admin attribute will always be cast to a boolean when you access it, even if the underlying value is stored in the database as an integer:

1$user = App\User::find(1);
2 
3if ($user->is_admin) {
4    //
5}

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

if ($user->is_admin) {
    //
}

Attributes that are null will not be cast. In addition, you should never define a cast (or an attribute) that has the same name as a relationship.

Custom Casts

Laravel has a variety of built-in, helpful cast types; however, you may occasionally need to define your own cast types. You may accomplish this by defining a class that implements the CastsAttributes interface.

Classes that implement this interface must define a get and set method. The get method is responsible for transforming a raw value from the database into a cast value, while the set method should transform a cast value into a raw value that can be stored in the database. As an example, we will re-implement the built-in json cast type as a custom cast type:

 1<?php
 2 
 3namespace App\Casts;
 4 
 5use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
 6 
 7class Json implements CastsAttributes
 8{
 9    /**
10     * Cast the given value.
11     *
12     * @param  \Illuminate\Database\Eloquent\Model  $model
13     * @param  string  $key
14     * @param  mixed  $value
15     * @param  array  $attributes
16     * @return array
17     */
18    public function get($model, $key, $value, $attributes)
19    {
20        return json_decode($value, true);
21    }
22 
23    /**
24     * Prepare the given value for storage.
25     *
26     * @param  \Illuminate\Database\Eloquent\Model  $model
27     * @param  string  $key
28     * @param  array  $value
29     * @param  array  $attributes
30     * @return string
31     */
32    public function set($model, $key, $value, $attributes)
33    {
34        return json_encode($value);
35    }
36}

<?php

namespace App\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;

class Json implements CastsAttributes
{
    /**
     * Cast the given value.
     *
     * @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);
    }

    /**
     * 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 json_encode($value);
    }
}

Once you have defined a custom cast type, you may attach it to a model attribute using its class name:

 1<?php
 2 
 3namespace App;
 4 
 5use App\Casts\Json;
 6use Illuminate\Database\Eloquent\Model;
 7 
 8class User extends Model
 9{
10    /**
11     * The attributes that should be cast.
12     *
13     * @var array
14     */
15    protected $casts = [
16        'options' => Json::class,
17    ];
18}

<?php

namespace App;

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

class User extends Model
{
    /**
     * The attributes that should be cast.
     *
     * @var array
     */
    protected $casts = [
        'options' => Json::class,
    ];
}

Value Object Casting

You are not limited to casting values to primitive types. You may also cast values to objects. Defining custom casts that cast values to objects is very similar to casting to primitive types; however, the set method should return an array of key / value pairs that will be used to set raw, storable values on the model.

As an example, we will define a custom cast class that casts multiple model values into a single Address value object. We will assume the Address value has two public properties: lineOne and lineTwo:

 1<?php
 2 
 3namespace App\Casts;
 4 
 5use App\Address;
 6use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
 7use InvalidArgumentException;
 8 
 9class Address implements CastsAttributes
10{
11    /**
12     * Cast the given value.
13     *
14     * @param  \Illuminate\Database\Eloquent\Model  $model
15     * @param  string  $key
16     * @param  mixed  $value
17     * @param  array  $attributes
18     * @return \App\Address
19     */
20    public function get($model, $key, $value, $attributes)
21    {
22        return new Address(
23            $attributes['address_line_one'],
24            $attributes['address_line_two']
25        );
26    }
27 
28    /**
29     * Prepare the given value for storage.
30     *
31     * @param  \Illuminate\Database\Eloquent\Model  $model
32     * @param  string  $key
33     * @param  \App\Address  $value
34     * @param  array  $attributes
35     * @return array
36     */
37    public function set($model, $key, $value, $attributes)
38    {
39        if (! $value instanceof Address) {
40            throw new InvalidArgumentException('The given value is not an Address instance.');
41        }
42 
43        return [
44            'address_line_one' => $value->lineOne,
45            'address_line_two' => $value->lineTwo,
46        ];
47    }
48}

<?php

namespace App\Casts;

use App\Address;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use InvalidArgumentException;

class Address implements CastsAttributes
{
    /**
     * Cast the given value.
     *
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @param  string  $key
     * @param  mixed  $value
     * @param  array  $attributes
     * @return \App\Address
     */
    public function get($model, $key, $value, $attributes)
    {
        return new Address(
            $attributes['address_line_one'],
            $attributes['address_line_two']
        );
    }

    /**
     * Prepare the given value for storage.
     *
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @param  string  $key
     * @param  \App\Address  $value
     * @param  array  $attributes
     * @return array
     */
    public function set($model, $key, $value, $attributes)
    {
        if (! $value instanceof Address) {
            throw new InvalidArgumentException('The given value is not an Address instance.');
        }

        return [
            'address_line_one' => $value->lineOne,
            'address_line_two' => $value->lineTwo,
        ];
    }
}

When casting to value objects, any changes made to the value object will automatically be synced back to the model before the model is saved:

1$user = App\User::find(1);
2 
3$user->address->lineOne = 'Updated Address Value';
4 
5$user->save();

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

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

$user->save();

If you plan to serialize your Eloquent models containing value objects to JSON or arrays, you should implement the Illuminate\Contracts\Support\Arrayable and JsonSerializable interfaces on the value object.

Inbound Casting

Occasionally, you may need to write a custom cast that only transforms values that are being set on the model and does not perform any operations when attributes are being retrieved from the model. A classic example of an inbound only cast is a "hashing" cast. Inbound only custom casts should implement the CastsInboundAttributes interface, which only requires a set method to be defined.

 1<?php
 2 
 3namespace App\Casts;
 4 
 5use Illuminate\Contracts\Database\Eloquent\CastsInboundAttributes;
 6 
 7class Hash implements CastsInboundAttributes
 8{
 9    /**
10     * The hashing algorithm.
11     *
12     * @var string
13     */
14    protected $algorithm;
15 
16    /**
17     * Create a new cast class instance.
18     *
19     * @param  string|null  $algorithm
20     * @return void
21     */
22    public function __construct($algorithm = null)
23    {
24        $this->algorithm = $algorithm;
25    }
26 
27    /**
28     * Prepare the given value for storage.
29     *
30     * @param  \Illuminate\Database\Eloquent\Model  $model
31     * @param  string  $key
32     * @param  array  $value
33     * @param  array  $attributes
34     * @return string
35     */
36    public function set($model, $key, $value, $attributes)
37    {
38        return is_null($this->algorithm)
39                    ? bcrypt($value)
40                    : hash($this->algorithm, $value);
41    }
42}

<?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);
    }
}

Cast Parameters

When attaching a custom cast to a model, cast parameters may be specified by separating them from the class name using a : character and comma-delimiting multiple parameters. The parameters will be passed to the constructor of the cast class:

1/**
2 * The attributes that should be cast.
3 *
4 * @var array
5 */
6protected $casts = [
7    'secret' => Hash::class.':sha256',
8];

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

Castables

Instead of attaching the custom cast to your model, you may alternatively attach a class that implements the Illuminate\Contracts\Database\Eloquent\Castable interface:

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

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

Objects that implement the Castable interface must define a castUsing method that returns the class name of the custom caster class that is responsible for casting to and from the Castable class:

 1<?php
 2 
 3namespace App;
 4 
 5use Illuminate\Contracts\Database\Eloquent\Castable;
 6use App\Casts\Address as AddressCast;
 7 
 8class Address implements Castable
 9{
10    /**
11     * Get the name of the caster class to use when casting from / to this cast target.
12     *
13     * @return string
14     */
15    public static function castUsing()
16    {
17        return AddressCast::class;
18    }
19}

<?php

namespace App;

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;
    }
}

When using Castable classes, you may still provide arguments in the $casts definition. The arguments will be passed directly to the caster class:

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

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

Array & JSON Casting

The array cast type is particularly useful when working with columns that are stored as serialized JSON. For example, if your database has a JSON or TEXT field type that contains serialized JSON, adding the array cast to that attribute will automatically deserialize the attribute to a PHP array when you access it on your Eloquent model:

 1<?php
 2 
 3namespace App;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class User extends Model
 8{
 9    /**
10     * The attributes that should be cast.
11     *
12     * @var array
13     */
14    protected $casts = [
15        'options' => 'array',
16    ];
17}

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The attributes that should be cast.
     *
     * @var array
     */
    protected $casts = [
        'options' => 'array',
    ];
}

Once the cast is defined, you may access the options attribute and it will automatically be deserialized from JSON into a PHP array. When you set the value of the options attribute, the given array will automatically be serialized back into JSON for storage:

1$user = App\User::find(1);
2 
3$options = $user->options;
4 
5$options['key'] = 'value';
6 
7$user->options = $options;
8 
9$user->save();

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

$options = $user->options;

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

$user->options = $options;

$user->save();

Date Casting

When using the date or datetime cast type, you may specify the date's format. This format will be used when the model is serialized to an array or JSON:

1/**
2 * The attributes that should be cast.
3 *
4 * @var array
5 */
6protected $casts = [
7    'created_at' => 'datetime:Y-m-d',
8];

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

Query Time Casting

Sometimes you may need to apply casts while executing a query, such as when selecting a raw value from a table. For example, consider the following query:

1use App\Post;
2use App\User;
3 
4$users = User::select([
5    'users.*',
6    'last_posted_at' => Post::selectRaw('MAX(created_at)')
7            ->whereColumn('user_id', 'users.id')
8])->get();

use App\Post;
use App\User;

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

The last_posted_at attribute on the results of this query will be a raw string. It would be convenient if we could apply a date cast to this attribute when executing the query. To accomplish this, we may use the withCasts method:

1$users = User::select([
2    'users.*',
3    'last_posted_at' => Post::selectRaw('MAX(created_at)')
4            ->whereColumn('user_id', 'users.id')
5])->withCasts([
6    'last_posted_at' => 'datetime'
7])->get();

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

Prologue

Getting Started

Architecture Concepts

The Basics

Frontend

Security

Digging Deeper

Database

Eloquent ORM

Testing

Official Packages

Eloquent: Mutators

Introduction

Accessors & Mutators

Defining An Accessor

Defining A Mutator

Date Mutators

Date Formats

Attribute Casting

Custom Casts

Value Object Casting

Inbound Casting

Cast Parameters

Castables

Array & JSON Casting

Date Casting

Query Time Casting

Products

Packages

Resources