Saltar al contenido principal

​
Introducción

Al construir APIs con Laravel, a menudo necesitas convertir modelos y sus relaciones a arrays o JSON. Eloquent incluye métodos convenientes para realizar estas conversiones, así como funciones para controlar qué atributos aparecen en la representación serializada del modelo.
Para una serialización JSON más robusta de modelos y colecciones Eloquent, consulta la documentación de Eloquent API Resources.

​
Modelos y arrays

​
Serialización a array

Para convertir un modelo y las relaciones que ha cargado a un array, usa el método toArray. El método es recursivo, por lo que todos los atributos y todas las relaciones (incluidas las relaciones de las relaciones) se convertirán en un array. 
use App\Models\User;

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

return $user->toArray();
Con el método attributesToArray puedes convertir solo los atributos del modelo sin las relaciones. 
$user = User::first();

return $user->attributesToArray();
Para convertir una colección entera de modelos a un array, invoca toArray sobre la instancia de la colección. 
$users = User::all();

return $users->toArray();

​
Serialización a JSON

Para convertir un modelo a JSON, usa el método toJson. Al igual que toArray, toJson es recursivo, por lo que todos los atributos y relaciones se convierten a JSON. También puedes indicar las opciones de codificación JSON soportadas por PHP. 
use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);
También puedes castear un modelo o una colección a string. En ese caso se llama automáticamente al método toJson del modelo o colección. 
return (string) User::find(1);
Como al castear a string modelos y colecciones se convierten a JSON, puedes devolver objetos Eloquent directamente desde tus rutas o controladores. Laravel serializa automáticamente a JSON los modelos y colecciones Eloquent devueltos desde rutas o controladores. 
Route::get('/users', function () {
    return User::all();
});

​
Relaciones

Cuando un modelo Eloquent se convierte a JSON, sus relaciones cargadas se incluyen automáticamente como atributos del objeto JSON. Además, aunque los métodos de relación de Eloquent se definen en “camelCase”, los atributos JSON de las relaciones se convierten en “snake_case”.

​
Control de la visibilidad de atributos

​
Ocultar atributos

A veces querrás restringir atributos como la contraseña dentro de la representación en array o JSON del modelo. Para ello, usa el atributo Hidden en el modelo. Los atributos listados en Hidden no se incluyen en la representación serializada. 
<?php

namespace App\Models;

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

#[Hidden(['password'])]
class User extends Model
{
    // ...
}
Para ocultar una relación, añade el nombre del método de la relación al atributo Hidden del modelo Eloquent.

​
Exponer atributos

Con el atributo Visible puedes definir una “lista blanca” de atributos que deben incluirse en la representación en array o JSON del modelo. Todos los atributos no presentes en Visible se ocultarán cuando el modelo se convierta a array o 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
{
    // ...
}

​
Mostrar u ocultar atributos temporalmente

Para mostrar en una instancia concreta un atributo que normalmente está oculto, usa makeVisible o mergeVisible. Estos métodos devuelven la instancia del modelo. 
return $user->makeVisible('attribute')->toArray();

return $user->mergeVisible(['name', 'email'])->toArray();
Al contrario, para ocultar atributos que normalmente son visibles, usa makeHidden o mergeHidden. 
return $user->makeHidden('attribute')->toArray();

return $user->mergeHidden(['name', 'email'])->toArray();
Para sobrescribir por completo la lista de atributos visibles u ocultos temporalmente, usa setVisible y setHidden. 
return $user->setVisible(['id', 'name'])->toArray();

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

​
Atributos añadidos (appends)

Al convertir un modelo a array o JSON, a veces querrás añadir atributos que no tienen una columna correspondiente en la base de datos. Para hacerlo, primero define un accessor para el valor. 
<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * Determina si el usuario es administrador.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}
Para incluir siempre el accessor en la representación en array y JSON del modelo, usa el atributo Appends. Aunque los métodos de accessor se definen en “camelCase”, el nombre del atributo usa normalmente la representación serializada en “snake_case”. 
<?php

namespace App\Models;

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

#[Appends(['is_admin'])]
class User extends Model
{
    // ...
}
Una vez añadido a la lista appends, el atributo se incluye tanto en el array como en la representación JSON del modelo. Los atributos de appends también respetan las configuraciones visible y hidden del modelo.

​
Añadir en tiempo de ejecución

En tiempo de ejecución puedes indicar a la instancia del modelo que añada atributos adicionales con append o mergeAppends. Con setAppends puedes sobrescribir por completo la lista de propiedades añadidas para una instancia concreta. 
return $user->append('is_admin')->toArray();

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

return $user->setAppends(['is_admin'])->toArray();
Para eliminar del modelo todas las propiedades añadidas, usa withoutAppends. 
return $user->withoutAppends()->toArray();

​
Serialización de fechas

​
Personalizar el formato de fecha por defecto

Sobrescribiendo el método serializeDate puedes personalizar el formato de serialización por defecto. Este método no afecta al formato que se usa al guardar en la base de datos. 
/**
 * Prepara la fecha para la serialización a array/JSON.
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

​
Personalizar el formato de fecha por atributo

Especificando el formato de fecha en las declaraciones de cast del modelo puedes personalizar la serialización de cada atributo de fecha de Eloquent. 
protected function casts(): array
{
    return [
        'birthday' => 'date:Y-m-d',
        'joined_at' => 'datetime:Y-m-d H:00',
    ];
}
Última modificación el 13 de julio de 2026

Temas relacionados

Colecciones EloquentAccesores, mutadores y casts de EloquentGuía de actualización de Laravel 12 a 13RedisResumen de las novedades de Laravel 13