Introduction
Accessors, mutators, and attribute casting allow you to transform 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. Or, you may want to convert a JSON string that is stored in your database to an array when it is accessed via your Eloquent model.
Accessors & Mutators
Defining An Accessor
An accessor transforms an Eloquent attribute value when it is accessed. To define an accessor, create a protected method on your model to represent the accessible attribute. This method name should correspond to the "camel case" representation of the true underlying model attribute / database column when applicable.
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. All attribute accessor / mutator
methods must declare a return type-hint of
Illuminate\Database\Eloquent\Casts\Attribute
:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* Get the user's first name.
*
* @return \Illuminate\Database\Eloquent\Casts\Attribute
*/
protected function firstName(): Attribute
{
return Attribute::make(
get: fn ($value) => ucfirst($value),
);
}
}
All accessor methods return an Attribute
instance which
defines how the attribute will be accessed and, optionally, mutated. In
this example, we are only defining how the attribute will be accessed.
To do so, we supply the get
argument to the
Attribute
class constructor.
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 simply access the first_name
attribute on a model instance:
use App\Models\User;
$user = User::find(1);
$firstName = $user->first_name;
Note:
If you would like these computed values to be added to the array / JSON representations of your model, you will need to append them.
Building Value Objects From Multiple Attributes
Sometimes your accessor may need to transform multiple model
attributes into a single "value object". To do so, your get
closure may accept a second argument of $attributes
, which
will be automatically supplied to the closure and will contain an array
of all of the model's current attributes:
use App\Support\Address;
use Illuminate\Database\Eloquent\Casts\Attribute;
/**
* Interact with the user's address.
*
* @return \Illuminate\Database\Eloquent\Casts\Attribute
*/
protected function address(): Attribute
{
return Attribute::make(
get: fn ($value, $attributes) => new Address(
$attributes['address_line_one'],
$attributes['address_line_two'],
),
);
}
Accessor Caching
When returning value objects from accessors, any changes made to the value object will automatically be synced back to the model before the model is saved. This is possible because Eloquent retains instances returned by accessors so it can return the same instance each time the accessor is invoked:
use App\Models\User;
$user = User::find(1);
$user->address->lineOne = 'Updated Address Line 1 Value';
$user->address->lineTwo = 'Updated Address Line 2 Value';
$user->save();
However, you may sometimes wish to enable caching for primitive
values like strings and booleans, particularly if they are
computationally intensive. To accomplish this, you may invoke the
shouldCache
method when defining your accessor:
protected function hash(): Attribute
{
return Attribute::make(
get: fn ($value) => bcrypt(gzuncompress($value)),
)->shouldCache();
}
If you would like to disable the object caching behavior of
attributes, you may invoke the withoutObjectCaching
method
when defining the attribute:
/**
* Interact with the user's address.
*
* @return \Illuminate\Database\Eloquent\Casts\Attribute
*/
protected function address(): Attribute
{
return Attribute::make(
get: fn ($value, $attributes) => new Address(
$attributes['address_line_one'],
$attributes['address_line_two'],
),
)->withoutObjectCaching();
}
Defining A Mutator
A mutator transforms an Eloquent attribute value when it is set. To
define a mutator, you may provide the set
argument when
defining your attribute. 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\Models;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* Interact with the user's first name.
*
* @return \Illuminate\Database\Eloquent\Casts\Attribute
*/
protected function firstName(): Attribute
{
return Attribute::make(
get: fn ($value) => ucfirst($value),
set: fn ($value) => strtolower($value),
);
}
}
The mutator closure will receive the value that is being set on the
attribute, allowing you to manipulate the value and return the
manipulated value. To use our mutator, we only need to set the
first_name
attribute on an Eloquent model:
use App\Models\User;
$user = User::find(1);
$user->first_name = 'Sally';
In this example, the set
callback 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 model's internal $attributes
array.
Mutating Multiple Attributes
Sometimes your mutator may need to set multiple attributes on the
underlying model. To do so, you may return an array from the
set
closure. Each key in the array should correspond with
an underlying attribute / database column associated with the model:
use App\Support\Address;
use Illuminate\Database\Eloquent\Casts\Attribute;
/**
* Interact with the user's address.
*
* @return \Illuminate\Database\Eloquent\Casts\Attribute
*/
protected function address(): Attribute
{
return Attribute::make(
get: fn ($value, $attributes) => new Address(
$attributes['address_line_one'],
$attributes['address_line_two'],
),
set: fn (Address $value) => [
'address_line_one' => $value->lineOne,
'address_line_two' => $value->lineTwo,
],
);
}
Attribute Casting
Attribute casting provides functionality similar to accessors and
mutators without requiring you to define any additional methods on your
model. Instead, your model's $casts
property 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:
array
AsStringable::class
boolean
collection
date
datetime
immutable_date
immutable_datetime
decimal:<precision>
double
encrypted
encrypted:array
encrypted:collection
encrypted:object
float
integer
object
real
string
timestamp
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:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* The attributes that should be cast.
*
* @var array
*/
protected $casts = [
'is_admin' => 'boolean',
];
}
After defining the cast, 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\Models\User::find(1);
if ($user->is_admin) {
//
}
If you need to add a new, temporary cast at runtime, you may use the
mergeCasts
method. These cast definitions will be added to
any of the casts already defined on the model:
$user->mergeCasts([
'is_admin' => 'integer',
'options' => 'object',
]);
Warning!!
Attributes that arenull
will not be cast. In addition, you should never define a cast (or an attribute) that has the same name as a relationship.
Stringable Casting
You may use the
Illuminate\Database\Eloquent\Casts\AsStringable
cast class
to cast a model attribute to a fluent
Illuminate\Support\Stringable
object:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Casts\AsStringable;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* The attributes that should be cast.
*
* @var array
*/
protected $casts = [
'directory' => AsStringable::class,
];
}
Array & JSON Casting
The array
cast 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:
<?php
namespace App\Models;
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:
use App\Models\User;
$user = User::find(1);
$options = $user->options;
$options['key'] = 'value';
$user->options = $options;
$user->save();
To update a single field of a JSON attribute with a more terse
syntax, you may use the ->
operator when calling the
update
method:
$user = User::find(1);
$user->update(['options->key' => 'value']);
Array Object & Collection Casting
Although the standard array
cast is sufficient for many
applications, it does have some disadvantages. Since the
array
cast returns a primitive type, it is not possible to
mutate an offset of the array directly. For example, the following code
will trigger a PHP error:
$user = User::find(1);
$user->options['key'] = $value;
To solve this, Laravel offers an AsArrayObject
cast that
casts your JSON attribute to an ArrayObject
class. This feature is implemented using Laravel's custom cast implementation, which allows
Laravel to intelligently cache and transform the mutated object such
that individual offsets may be modified without triggering a PHP error.
To use the AsArrayObject
cast, simply assign it to an
attribute:
use Illuminate\Database\Eloquent\Casts\AsArrayObject;
/**
* The attributes that should be cast.
*
* @var array
*/
protected $casts = [
'options' => AsArrayObject::class,
];
Similarly, Laravel offers an AsCollection
cast that
casts your JSON attribute to a Laravel Collection instance:
use Illuminate\Database\Eloquent\Casts\AsCollection;
/**
* The attributes that should be cast.
*
* @var array
*/
protected $casts = [
'options' => AsCollection::class,
];
Date Casting
By default, Eloquent will cast 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 cast additional date attributes by defining
additional date casts within your model's $casts
property
array. Typically, dates should be cast using the datetime
or immutable_datetime
cast types.
When defining a date
or datetime
cast, you
may also specify the date's format. This format will be used when the model is serialized to an array or
JSON:
/**
* The attributes that should be cast.
*
* @var array
*/
protected $casts = [
'created_at' => 'datetime:Y-m-d',
];
When a column is cast as a date, you may set the corresponding model
attribute 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.
You may customize the default serialization format for all of your
model's dates by defining a serializeDate
method on your
model. This method does not affect how your dates are formatted for
storage in the database:
/**
* Prepare a date for array / JSON serialization.
*
* @param \DateTimeInterface $date
* @return string
*/
protected function serializeDate(DateTimeInterface $date)
{
return $date->format('Y-m-d');
}
To specify the format that should be used when actually storing a
model's dates within your database, you should define a
$dateFormat
property on your model:
/**
* The storage format of the model's date columns.
*
* @var string
*/
protected $dateFormat = 'U';
Date Casting, Serialization, & Timezones
By default, the date
and datetime
casts
will serialize dates to a UTC ISO-8601 date string
(1986-05-28T21:05:54.000000Z
), regardless of the timezone
specified in your application's timezone
configuration
option. You are strongly encouraged to always use this serialization
format, as well as to store your application's dates in the UTC timezone
by not changing your application's timezone
configuration
option from its default UTC
value. Consistently using the
UTC timezone throughout your application will provide the maximum level
of interoperability with other date manipulation libraries written in
PHP and JavaScript.
If a custom format is applied to the date
or
datetime
cast, such as datetime:Y-m-d H:i:s
,
the inner timezone of the Carbon instance will be used during date
serialization. Typically, this will be the timezone specified in your
application's timezone
configuration option.
Enum Casting
Warning!!
Enum casting is only available for PHP 8.1+.
Eloquent also allows you to cast your attribute values to PHP Enums.
To accomplish this, you may specify the attribute and enum you wish to
cast in your model's $casts
property array:
use App\Enums\ServerStatus;
/**
* The attributes that should be cast.
*
* @var array
*/
protected $casts = [
'status' => ServerStatus::class,
];
Once you have defined the cast on your model, the specified attribute will be automatically cast to and from an enum when you interact with the attribute:
if ($server->status == ServerStatus::Provisioned) {
$server->status = ServerStatus::Ready;
$server->save();
}
Casting Arrays Of Enums
Sometimes you may need your model to store an array of enum values
within a single column. To accomplish this, you may utilize the
AsEnumArrayObject
or AsEnumCollection
casts
provided by Laravel:
use App\Enums\ServerStatus;
use Illuminate\Database\Eloquent\Casts\AsEnumCollection;
/**
* The attributes that should be cast.
*
* @var array
*/
protected $casts = [
'statuses' => AsEnumCollection::class.':'.ServerStatus::class,
];
Encrypted Casting
The encrypted
cast will encrypt a model's attribute
value using Laravel's built-in encryption
features. In addition, the encrypted:array
,
encrypted:collection
, encrypted:object
,
AsEncryptedArrayObject
, and
AsEncryptedCollection
casts work like their unencrypted
counterparts; however, as you might expect, the underlying value is
encrypted when stored in your database.
As the final length of the encrypted text is not predictable and is
longer than its plain text counterpart, make sure the associated
database column is of TEXT
type or larger. In addition,
since the values are encrypted in the database, you will not be able to
query or search encrypted attribute values.
Key Rotation
As you may know, Laravel encrypts strings using the key
configuration value specified in your application's app
configuration file. Typically, this value corresponds to the value of
the APP_KEY
environment variable. If you need to rotate
your application's encryption key, you will need to manually re-encrypt
your encrypted attributes using the new key.
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:
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();
The last_posted_at
attribute on the results of this
query will be a simple string. It would be wonderful if we could apply a
datetime
cast to this attribute when executing the query.
Thankfully, we may accomplish this using the withCasts
method:
$users = User::select([
'users.*',
'last_posted_at' => Post::selectRaw('MAX(created_at)')
->whereColumn('user_id', 'users.id')
])->withCasts([
'last_posted_at' => 'datetime'
])->get();
Custom Casts
Laravel has a variety of built-in, helpful cast types; however, you
may occasionally need to define your own cast types. To create a cast,
execute the make:cast
Artisan command. The new cast class
will be placed in your app/Casts
directory:
php artisan make:cast Json
All custom cast classes implement 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:
<?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:
<?php
namespace App\Models;
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
:
<?php
namespace App\Casts;
use App\ValueObjects\Address as AddressValueObject;
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\ValueObjects\Address
*/
public function get($model, $key, $value, $attributes)
{
return new AddressValueObject(
$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\ValueObjects\Address $value
* @param array $attributes
* @return array
*/
public function set($model, $key, $value, $attributes)
{
if (! $value instanceof AddressValueObject) {
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:
use App\Models\User;
$user = User::find(1);
$user->address->lineOne = 'Updated Address Value';
$user->save();
Note:
If you plan to serialize your Eloquent models containing value objects to JSON or arrays, you should implement theIlluminate\Contracts\Support\Arrayable
andJsonSerializable
interfaces on the value object.
Array / JSON Serialization
When an Eloquent model is converted to an array or JSON using the
toArray
and toJson
methods, your custom cast
value objects will typically be serialized as well as long as they
implement the Illuminate\Contracts\Support\Arrayable
and
JsonSerializable
interfaces. However, when using value
objects provided by third-party libraries, you may not have the ability
to add these interfaces to the object.
Therefore, you may specify that your custom cast class will be
responsible for serializing the value object. To do so, your custom cast
class should implement the
Illuminate\Contracts\Database\Eloquent\SerializesCastableAttributes
interface. This interface states that your class should contain a
serialize
method which should return the serialized form of
your value object:
/**
* Get the serialized representation of the value.
*
* @param \Illuminate\Database\Eloquent\Model $model
* @param string $key
* @param mixed $value
* @param array $attributes
* @return mixed
*/
public function serialize($model, string $key, $value, array $attributes)
{
return (string) $value;
}
Inbound Casting
Occasionally, you may need to write a custom cast class 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.
Inbound only custom casts should implement the
CastsInboundAttributes
interface, which only requires a
set
method to be defined. The make:cast
Artisan command may be invoked with the --inbound
option to
generate an inbound only cast class:
php artisan make:cast Hash --inbound
A classic example of an inbound only cast is a "hashing" cast. For example, we may define a cast that hashes inbound values via a given algorithm:
<?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:
/**
* The attributes that should be cast.
*
* @var array
*/
protected $casts = [
'secret' => Hash::class.':sha256',
];
Castables
You may want to allow your application's value objects to define
their own custom cast classes. Instead of attaching the custom cast
class to your model, you may alternatively attach a value object class
that implements the
Illuminate\Contracts\Database\Eloquent\Castable
interface:
use App\Models\Address;
protected $casts = [
'address' => 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:
<?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.
*
* @param array $arguments
* @return string
*/
public static function castUsing(array $arguments)
{
return AddressCast::class;
}
}
When using Castable
classes, you may still provide
arguments in the $casts
definition. The arguments will be
passed to the castUsing
method:
use App\Models\Address;
protected $casts = [
'address' => Address::class.':argument',
];
Castables & Anonymous Cast Classes
By combining "castables" with PHP's anonymous
classes, you may define a value object and its casting logic as a
single castable object. To accomplish this, return an anonymous class
from your value object's castUsing
method. The anonymous
class should implement the CastsAttributes
interface:
<?php
namespace App\Models;
use Illuminate\Contracts\Database\Eloquent\Castable;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
class Address implements Castable
{
// ...
/**
* Get the caster class to use when casting from / to this cast target.
*
* @param array $arguments
* @return object|string
*/
public static function castUsing(array $arguments)
{
return new class implements CastsAttributes
{
public function get($model, $key, $value, $attributes)
{
return new Address(
$attributes['address_line_one'],
$attributes['address_line_two']
);
}
public function set($model, $key, $value, $attributes)
{
return [
'address_line_one' => $value->lineOne,
'address_line_two' => $value->lineTwo,
];
}
};
}
}