> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Serialización en Eloquent

> Explicamos cómo convertir modelos Eloquent a JSON y arrays, cómo controlar la visibilidad de atributos, cómo añadir atributos y cómo personalizar el formato de fechas.

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

<Info>
  Para una serialización JSON más robusta de modelos y colecciones Eloquent, consulta la documentación de [Eloquent API Resources](./eloquent-resources).
</Info>

## Modelos y arrays

### Serialización a array

Para convertir un modelo y las [relaciones](./eloquent-relationships) 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.

```php theme={null}
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.

```php theme={null}
$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.

```php theme={null}
$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](https://secure.php.net/manual/es/function.json-encode.php).

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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 theme={null}
<?php

namespace App\Models;

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

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

<Info>
  Para ocultar una relación, añade el nombre del método de la relación al atributo Hidden del modelo Eloquent.
</Info>

### 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 theme={null}
<?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.

```php theme={null}
return $user->makeVisible('attribute')->toArray();

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

Al contrario, para ocultar atributos que normalmente son visibles, usa `makeHidden` o `mergeHidden`.

```php theme={null}
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`.

```php theme={null}
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](./eloquent-mutators) para el valor.

```php theme={null}
<?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 theme={null}
<?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.

```php theme={null}
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`.

```php theme={null}
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.

```php theme={null}
/**
 * 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](./eloquent-mutators#attribute-casting) del modelo puedes personalizar la serialización de cada atributo de fecha de Eloquent.

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


## Related topics

- [Colecciones Eloquent](/es/eloquent-collections.md)
- [Accesores, mutadores y casts de Eloquent](/es/eloquent-mutators.md)
- [Guía de actualización de Laravel 12 a 13](/es/blog/upgrade-12-to-13.md)
- [Redis](/es/redis.md)
- [Resumen de las novedades de Laravel 13](/es/blog/laravel-13-new-features.md)