Introduction
Accessors and mutators allow you to format Eloquent attributes when retrieving them from a model or setting their value. 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 "camel" 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
first_name:
<?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 mutator, you may simply access the first_name
attribute:
$user = App\User::find(1);
$firstName = $user->first_name;Defining A Mutator
To define a mutator, define a setFooAttribute method on
your model where Foo is the "camel" 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:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* Set the user's first name.
*
* @param string $value
* @return string
*/
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:
$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 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 provides
an assortment of helpful methods, and extends the native PHP
DateTime class.
You may customize which fields are automatically mutated, and even
completely disable this mutation, by overriding the $dates
property of your model:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* The attributes that should be mutated to dates.
*
* @var array
*/
protected $dates = ['created_at', 'updated_at', 'deleted_at'];
}When a column is considered a date, you may set its value to a UNIX
timestamp, date string (Y-m-d), date-time string, and of
course a DateTime / Carbon instance, and the
date's value will automatically be correctly stored in your
database:
$user = App\User::find(1);
$user->deleted_at = Carbon::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:
$user = App\User::find(1);
return $user->deleted_at->getTimestamp();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, as well as
their format when the model is serialized to an array or JSON:
<?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, while the value is the type you wish
to cast the column to. The supported cast types are:
integer, real, float,
double, string, boolean,
object, array, collection,
date, datetime, and
timestamp.
For example, let's cast the is_admin attribute, which is
stored in our database as an integer (0 or 1)
to a boolean value:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* The attributes that should be casted to native types.
*
* @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:
$user = App\User::find(1);
if ($user->is_admin) {
//
}Array 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 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:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* The attributes that should be casted to native types.
*
* @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:
$user = App\User::find(1);
$options = $user->options;
$options['key'] = 'value';
$user->options = $options;
$user->save();