Eloquent serialization

Introduction

When you build an API with Laravel, you often need to convert models and their relationships into arrays or JSON. Eloquent includes convenient methods for these conversions and features that let you control which attributes appear in the serialized representation of a model.

For a more robust way to serialize Eloquent models and collections to JSON, see the Eloquent API resources documentation.

Models and arrays

Serializing to an array

Use the toArray method to convert a model and its loaded relationships to an array. The method works recursively, so every attribute and every relationship (including nested relationships) is converted to an array.

use App\Models\User;

$user = User::with('roles')->first();

return $user->toArray();

Use attributesToArray to convert only the model’s attributes to an array, without its relationships.

$user = User::first();

return $user->attributesToArray();

To convert an entire collection of models to an array, call toArray on the collection instance.

$users = User::all();

return $users->toArray();

Serializing to JSON

Use the toJson method to convert a model to JSON. Like toArray, toJson is recursive, so every attribute and relationship is converted to JSON. You can also pass any JSON encoding option supported by PHP.

use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

You can also cast a model or collection to a string, which automatically calls toJson.

return (string) User::find(1);

Because models and collections are converted to JSON when cast to a string, you can return Eloquent objects directly from your application’s routes or controllers. Laravel automatically serializes Eloquent models and collections returned from routes or controllers to JSON.

Route::get('/users', function () {
    return User::all();
});

Relationships

When an Eloquent model is converted to JSON, its loaded relationships are automatically included as attributes on the JSON object. Also, while Eloquent relationship methods are defined with “camelCase” names, the JSON attributes for the relationships use “snake_case”.

Controlling attribute visibility

Hiding attributes

You may want to limit attributes — such as passwords — from a model’s array or JSON representation. To do so, use the Hidden attribute on the model. Attributes listed on the Hidden attribute will not be included in the serialized representation of the model.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Model;

#[Hidden(['password'])]
class User extends Model
{
    // ...
}

To hide a relationship, add its method name to the model’s Hidden attribute.

Exposing attributes

Alternatively, use the Visible attribute to define an “allow list” of attributes that should be included in the model’s array and JSON representation. Every attribute not present in Visible is hidden when the model is converted to an array or JSON.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Visible;
use Illuminate\Database\Eloquent\Model;

#[Visible(['first_name', 'last_name'])]
class User extends Model
{
    // ...
}

Temporarily showing or hiding attributes

To make normally hidden attributes visible on a specific model instance, use the makeVisible or mergeVisible methods. makeVisible returns the model instance.

return $user->makeVisible('attribute')->toArray();

return $user->mergeVisible(['name', 'email'])->toArray();

Conversely, use makeHidden or mergeHidden to hide attributes that are normally visible.

return $user->makeHidden('attribute')->toArray();

return $user->mergeHidden(['name', 'email'])->toArray();

To fully override all visible or hidden attributes at once, use setVisible and setHidden respectively.

return $user->setVisible(['id', 'name'])->toArray();

return $user->setHidden(['email', 'password', 'remember_token'])->toArray();

Appended attributes

When converting a model to an array or JSON, you may want to add attributes that don’t have a corresponding column in the database. To do so, first define an accessor for the value.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Determine whether the user is an administrator.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

If you want an accessor to always be added to a model’s array and JSON representation, use the Appends attribute on the model. Even though accessor PHP methods are defined in “camelCase”, attribute names typically use the “snake_case” serialized form.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Appends;
use Illuminate\Database\Eloquent\Model;

#[Appends(['is_admin'])]
class User extends Model
{
    // ...
}

Once an attribute is added to the appends list, it’s included in both the model’s array and JSON representation. Attributes in the appends array also respect the visible and hidden settings on the model.

Appending at runtime

At runtime, use the append or mergeAppends methods to instruct a model instance to append additional attributes. You can also use the setAppends method to override the entire array of appended properties on a specific model instance.

return $user->append('is_admin')->toArray();

return $user->mergeAppends(['is_admin', 'status'])->toArray();

return $user->setAppends(['is_admin'])->toArray();

Use withoutAppends to remove all appended properties from a model.

return $user->withoutAppends()->toArray();

Date serialization

Customizing the default date format

You can customize the default serialization format by overriding the serializeDate method. This method does not affect the format used when writing dates to the database.

/**
 * Prepare a date for array / JSON serialization.
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

Customizing the date format per attribute

You can customize the serialization format of individual Eloquent date attributes by specifying the date format in the model’s cast declaration.

protected function casts(): array
{
    return [
        'birthday' => 'date:Y-m-d',
        'joined_at' => 'datetime:Y-m-d H:00',
    ];
}

Architecture

Database

Eloquent

Security

Events

Mail and Notifications

Payments

Asynchronous Processing

Real-time Communication

Scheduling

Cache and Optimization

Internationalization

Files and Storage

Debugging and Monitoring

Console and CLI

Performance

Frontend

AI Development

Development Environment

Introduction

Models and arrays

Serializing to an array

Serializing to JSON

Relationships

Controlling attribute visibility

Hiding attributes

Exposing attributes

Temporarily showing or hiding attributes

Appended attributes

Appending at runtime

Date serialization

Customizing the default date format

Customizing the date format per attribute

​Introduction

​Models and arrays

​Serializing to an array

​Serializing to JSON

​Relationships

​Controlling attribute visibility

​Hiding attributes

​Exposing attributes

​Temporarily showing or hiding attributes

​Appended attributes

​Appending at runtime

​Date serialization

​Customizing the default date format

​Customizing the date format per attribute

Introduction

Models and arrays

Serializing to an array

Serializing to JSON

Relationships

Controlling attribute visibility

Hiding attributes

Exposing attributes

Temporarily showing or hiding attributes

Appended attributes

Appending at runtime

Date serialization

Customizing the default date format

Customizing the date format per attribute