By Model casts, mutators, and accessors are something you work with a lot when building Laravel applications. They play an essential role in how you interact with your models and their underlying data.
Laravel ships with a variety of handy, built-in casts which cover the majority of your use cases. But there may be times when you need to create your own custom casts to handle storing and retrieving data in a specific way.
In this article, we'll examine what model casts, mutators, and accessors are in Laravel. We'll then explore how you can create your own custom cast classes and write tests for them.
By the end of the article, you should feel confident enough to start using custom Laravel casts in your applications.
What are mutators and accessors in Laravel?
"Mutators" and "accessors" are two key concepts in Laravel that allow you to manipulate your model data when it's being stored or retrieved from the database.
When storing or updating a model in the database, mutators convert the data into a format that can be stored in the database.
When retrieving a model from the database, accessors convert the data back into a format that can be used in your application.
There is already some great documentation on mutators and accessors, so we won't go into too much detail about them in this article. But I'll give you a quick overview of what they are and how you might use them in your applications.
Accessors in Laravel models
Imagine we have an App\Models\User model that has first_name and last_name fields. Rather than needing to concatenate these fields every time we want to get the full name, we can use an accessor to do this for us.
Let's take this example App\Models\User model:
declare(strict_types=1);
namespace App\Models;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Foundation\Auth\User as Authenticatable;
final class User extends Authenticatable
{
// ...
protected function fullName(): Attribute
{
return Attribute::get(
fn(): string => $this->first_name.' '.$this->last_name,
);
}
}
In the example, we've added a fullName method and specified that it's an accessor by using the Illuminate\Database\Eloquent\Casts\Attribute::get method which returns an instance of Illuminate\Database\Eloquent\Casts\Attribute. By doing this, we have specified that whenever an attempt is made to access the full_name attribute of the model, the result of the closure will be returned.
For example, let's imagine we have a user with the first_name of "John" and the last_name of "Smith". By using the accessor, we can now access the full_name attribute like this:
use App\Models\User;
$user = User::find(1);
$fullName = $user->full_name; // "John Smith"
Mutators in Laravel models
Similar to accessors, we can also define mutators for our Laravel models. These mutators are used to manipulate data before it's stored in the database.
These are handy for scenarios like ensuring data is stored in a consistent format. For example, you might want to convert all email addresses to lowercase before storing them in the database.
Let's take a look at how we could do this in our App\Models\User model:
declare(strict_types=1);
namespace App\Models;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Foundation\Auth\User as Authenticatable;
final class User extends Authenticatable
{
// ...
protected function email(): Attribute
{
return Attribute::set(
fn(string $value): string => strtolower($value),
);
}
}
In our example, we can see that we've added an email method to our App\Models\User model. We've then specified that it's a mutator by using the Illuminate\Database\Eloquent\Casts\Attribute::set method which returns an instance of Illuminate\Database\Eloquent\Casts\Attribute. By doing this, we have specified that whenever an attempt is made to store a value in the email attribute of the model, the result of the closure will be stored in the database.
For example, let's assume we want to update the email address of a user with an ID of 1 to HELLO@EXAMPLE.COM:
use App\Models\User;
$user = User::find(1);
$user->update(['email' => 'HELLO@EXAMPLE.COM']);
$user->email; // hello@example.com
Using an accessor and mutator for the same field
In our previous examples, we've only defined an accessor or mutator for a field. But there may be times when you'd like to use both an accessor and mutator for the same field.
Let's take this example App\Models\User model from the Laravel documentation:
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.
*/
protected function firstName(): Attribute
{
return Attribute::make(
get: fn (string $value) => ucfirst($value),
set: fn (string $value) => strtolower($value),
);
}
}
In the example above, we can see that the user model has an accessor and a mutator for the first_name field. The accessor (defined by the closure passed to the get parameter) will capitalize the first letter of the first name when it's retrieved from the database, and the mutator (defined by the closure passed to the set parameter) will convert the first name to lowercase before storing it in the database.
Note: The example above is purely for illustrative purposes to demonstrate how to use an accessor and mutator on the same field. You'll likely want to avoid using this same logic in a real-life application as it could cause names such as "McDonald" to be stored as "mcdonald" and then retrieved as "Mcdonald".
What are casts in Laravel?
There may be times when the logic used in your mutators and accessors is complex or intended to be reused across multiple models. In these cases, you might want to consider using a "cast".
Laravel model casts are typically classes that define the logic for how a model's attribute should be stored or retrieved from the database. They can be used to handle complex logic that would be difficult or messy to manage in a mutator or accessor.
At the time of writing, Laravel ships with 21 casts that you can use out of the box.
You may also be interested in checking out the "A guide to encryption and hashing in Laravel" article which shows how to use the encrypted cast to automatically encrypt your model's sensitive data when storing it, and then decrypt it when retrieving it.
To understand how to use Laravel casts in your models, let's look at an example App\Models\User class and then discuss what's being done:
declare(strict_types=1);
namespace App\Models;
use Illuminate\Foundation\Auth\User as Authenticatable;
final class User extends Authenticatable
{
// ...
/**
* Get the attributes that should be cast.
*
* @return array<string, string>
*/
protected function casts(): array
{
return [
'email_verified_at' => 'datetime',
// ...
];
}
}
In the example above, we have used the casts method to define which of the model's attributes should be cast using mutators and accessors. In this case, we've specified that the email_verified_at attribute should use the datetime cast.
The datetime cast is used to:
- Convert the
email_verified_atfield to a format that can be stored in the database. - Convert the
email_verified_atfield back to an instance ofCarbon\Carbonwhen it's retrieved from the database (assuming you haven't changed the default behaviour of which class the date should be resolved to).
For instance, say we have an App\Models\User model with an email_verified_at value stored in the database as 2025-03-13 12:00:00. By applying the datetime cast, the value will be converted to an instance of Carbon\Carbon when it's retrieved from the database. This means we can then interact with the value and do things such as $user->email_verified_at->addDays(2), $user->email_verified_at->format('Y-m-d'), etc.
What are custom casts in Laravel?
The casts that ship with Laravel will likely cover the majority of your use cases. However, there may be times when you need to create your own custom casts to handle storing and retrieving data in a specific way.
For example, you may want to store an object as JSON in a single column in your database. Then when retrieving the model, you may want to convert the JSON back into an object (such as a value object) so you can interact with it more meaningfully.
How to create custom Laravel casts
To understand how to use custom casts in your models, we'll create a cast to allow storing a simple value object (VO) in a single column in the database. We'll then show how to apply the cast to the model.
Please note, it could be argued that this data would be better stored in separate columns or a separate table, rather than being stored as JSON in a single column. But I've chosen to keep the example simple so we can focus on how to use custom casts for storing and retrieving data rather than the complexity of the data being stored.
Let's start by outlining exactly what we want our casting logic to achieve. We'll assume we are building a web application that provides the user with the ability to toggle which notifications they should receive. There are three types of notifications: marketing, announcements, and system. We'll store the user's notification preferences in a notification_preferences JSON column on the users table so they can be easily retrieved and updated.
In the following diagram, we can see the data flow that we'll achieve by creating our custom cast:
To get started, we'll first create a App\ValueObjects\Notifications class to represent the user's notification preferences:
declare(strict_types=1);
namespace App\ValueObjects\Notifications;
final class Preferences implements Castable
{
public function __construct(
public bool $marketing,
public bool $announcements,
public bool $system,
) {}
}
As we can see there are 3 properties on the class, each representing a different type of notification.
We can then create the actual cast class which is responsible for converting the value object. We'll do this by running the following command in the project root to create the new cast class:
php artisan make:cast NotificationPreferences
You should now have a new App\Casts\NotificationPreferences class. Let's update the Laravel cast to convert the value object to and from JSON and then we'll discuss what's being done:
declare(strict_types=1);
namespace App\Casts;
use App\ValueObjects\Notifications\Preferences;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use Illuminate\Database\Eloquent\Model;
use JsonException;
final readonly class NotificationPreferences implements CastsAttributes
{
/**
* Cast the given value.
*
* @param array<string, mixed> $attributes
* @throws JsonException
*/
public function get(
Model $model,
string $key,
mixed $value,
array $attributes,
): ?Preferences {
// If no notification preferences are stored, return null.
if (!$value) {
return null;
}
// Decode the JSON string into an associative array.
$preferencesArray = json_decode(
json: $value,
associative: true,
depth: 512,
flags: JSON_THROW_ON_ERROR
);
// Build and return an instance of Preferences from the decoded array.
return new Preferences(
$preferencesArray['marketing'],
$preferencesArray['announcements'],
$preferencesArray['system'],
);
}
/**
* Prepare the given value for storage.
*
* @param array<string, mixed> $attributes
* @throws JsonException
*/
public function set(
Model $model,
string $key,
mixed $value,
array $attributes
): ?string {
// If no notification preferences are passed, return null.
if (!$value) {
return null;
}
// Ensure the value is an instance of Preferences so we're working
// with the correct data.
if (!$value instanceof Preferences) {
throw new \InvalidArgumentException(
'The given value is not an instance of ' . Preferences::class
);
}
// Return the JSON representation of the Preferences instance.
return json_encode(
$value,
JSON_THROW_ON_ERROR,
);
}
}
In the code above, we can see that we have 2 methods:
get- This method is responsible for converting the JSON string stored in the database back into an instance ofApp\ValueObjects\Notifications\Preferences.set- This method is responsible for converting theApp\ValueObjects\Notifications\Preferencesinstance back into a JSON string so it can be stored in the database.
In the get method, we first start by checking whether the value is null (meaning there are no notification preferences stored). If this is the case, we'll return null; however in a real-life application, you may want to return a default instance of App\ValueObjects\Notifications\Preferences with all values set to false. After this, we're then decoding the JSON to an associative array and then using this to build and return an instance of App\ValueObjects\Notifications\Preferences.
In the set method, we first check whether we're trying to store null (meaning there are no notification preferences to store). If this is the case, we return null, meaning the column will be set to null in the database. Similar to the get method, you may prefer to store some sensible defaults here instead of just null. We then ensure the value is an instance of App\ValueObjects\Notifications\Preferences so we can be sure we're working with the correct data type. If the value is not an instance of App\ValueObjects\Notifications\Preferences, we throw an exception. Finally, we return the JSON representation of the App\ValueObjects\Notifications\Preferences instance which will then be stored in the database.
Now, let's apply the cast to the App\Models\User model. We can do this by updating the casts method in the model like so:
declare(strict_types=1);
namespace App\Models;
use App\Casts\NotificationPreferences;
use Illuminate\Foundation\Auth\User as Authenticatable;
final class User extends Authenticatable
{
// ...
/**
* Get the attributes that should be cast.
*
* @return array<string, string>
*/
protected function casts(): array
{
return [
// ...
'notification_preferences' => NotificationPreferences::class,
];
}
}
In the example above, we've specified that the notification_preferences attribute should use the App\Casts\NotificationPreferences cast.
This means we can now store the user's notification preferences like so:
use App\Models\User;
use App\ValueObjects\Notifications\Preferences;
// Fetch the user.
$user = User::find(1);
// Create the notification preferences value object. In a real-life
// application, the values may have come from an HTTP request.
$preferences = new Preferences(
marketing: true,
announcements: false,
system: true
);
// Store the notification preferences.
$user->update([
'notification_preferences' => $preferences,
]);
Running the above code would result in the raw value being stored in the notification_preferences column on the users table as the following JSON string:
{"marketing":true,"announcements":false,"system":true}
We could then read the user's notification preferences (which will be an instance of App\ValueObjects\Notifications\Preferences) like so:
$user->notification_preferences->marketing; // true
$user->notification_preferences->announcements; // false
$user->notification_preferences->system; // true
As we've highlighted here, creating custom casts in Laravel can be quite handy; especially when you want to automatically cast complex data types for storing in the database.
How to test Laravel custom casts
It's important that you write tests to ensure that your custom casts work as expected.
There are several options for testing your custom casts. You could write isolated unit tests for both of the methods in the cast class, or you could write feature tests to ensure the model's attributes are being cast correctly. Both options are valid and can be used together to provide a good level of confidence. However, in a lot of cases, I prefer to write the feature tests so I can test the cast in the context of the model instance. This is only down to my personal preference though, so please, use what works best for you and your project.
We'll want to test the following scenarios for our App\Casts\NotificationPreferences cast:
- A user's notification preferences can be stored correctly in the database.
- A user's notification preferences can be retrieved correctly from the database.
- If no notification preferences are stored,
nullis returned when retrieving the value from the database. - An exception is thrown if we try to store an invalid value.
Let's write some tests and then we'll discuss what's being done:
declare(strict_types=1);
namespace Feature\Models\User;
use App\Models\User;
use App\ValueObjects\Notifications\Preferences;
use Illuminate\Foundation\Testing\LazilyRefreshDatabase;
use Illuminate\Support\Facades\DB;
use PHPUnit\Framework\Attributes\Test;
use Tests\TestCase;
final class NotificationPreferencesTest extends TestCase
{
use LazilyRefreshDatabase;
#[Test]
public function notification_preferences_can_be_stored_correctly(): void
{
// Create a user with notification preferences.
$user = User::factory()->create([
'notification_preferences' => new Preferences(
marketing: true,
announcements: false,
system: false,
),
]);
// Assert the user's notification preferences are stored correctly
// in the database.
$this->assertDatabaseHas('users', [
'id' => $user->id,
'notification_preferences' => '{"marketing":true,"announcements":false,"system":false}',
]);
}
#[Test]
public function notification_preferences_can_be_retrieved_correctly(): void
{
// Create a user with no notification preferences.
$user = User::factory()->create([
'notification_preferences' => null,
]);
// Manually update the user's notification preferences. We're doing
// this to avoid interacting with the cast.
DB::table('users')
->where('id', $user->id)
->update(['notification_preferences' => '{"marketing":true,"announcements":false,"system":false}']);
// Refresh the user model to ensure we're working with the latest data.
$user->refresh();
// Test the user's notification preferences are retrieved correctly.
$this->assertInstanceOf(Preferences::class, $user->notification_preferences);
$this->assertTrue($user->notification_preferences->marketing);
$this->assertFalse($user->notification_preferences->announcements);
$this->assertFalse($user->notification_preferences->system);
}
#[Test]
public function null_is_returned_if_fetching_empty_preferences(): void
{
// Create a user with no notification preferences.
$user = User::factory()->create([
'notification_preferences' => null,
]);
$user->refresh();
// Assert that null is returned when fetching empty preferences.
$this->assertNull($user->notification_preferences);
}
#[Test]
public function exception_is_thrown_if_trying_to_store_invalid_preferences(): void
{
// Specify that we expect an exception to be thrown in the test.
$this->expectException(\InvalidArgumentException::class);
$this->expectExceptionMessage(
'The given value is not an instance of App\ValueObjects\Notifications\Preferences'
);
// Attempt to create a user with invalid notification preferences. This
// should trigger the exception to be thrown.
User::factory()->create([
'notification_preferences' => 'INVALID',
]);
}
}
By having the above tests in place, we can have confidence that the cast works as expected when used in the context of the App\Models\User model.
Catch issues with custom casts in Laravel
In this article, we've looked at what model casts, mutators, and accessors are in Laravel. We've then covered how to create your own custom Laravel casts and write tests for them to ensure they work as expected.
You should now feel confident enough to start using custom casts in your Laravel applications.
Remember, even with a good-quality test suite in place, issues can still slip through the cracks. So you may want to consider using an error-monitoring service, such as Honeybadger, to catch any issues that arise in production. By doing this, you can be notified of any bugs in your application and fix them before they impact your users.
If you enjoyed this article, you may also want to sign up for the Honeybadger newsletter so you'll be notified when new articles are published.
