Eloquent: Mutators

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 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 .

Defining An Accessor

To define an accessor, create a 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 first_name:

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:

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

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

By default, Eloquent will convert the created_at and 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:

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:

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

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

  1. $user = App\User::find(1);
  3. return $user->deleted_at->getTimestamp();
  1. <?php
  3. namespace App;
  5. use Illuminate\Database\Eloquent\Model;
  7. class 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. }

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, , 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:

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:

  2. if ($user->is_admin) {
  3.     //
  4. }

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:

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

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);
  3. $options = $user->options;
  5. $options['key'] = 'value';
  7. $user->options = $options;