Eloquent: Serialización

• Introducción
• Serialización de modelos y colecciones
  • Serialización a arrays
  • Serialización a JSON
• Ocultar atributos del JSON
• Agregar valores al JSON
• Serialización de fechas

#Introducción

Al construir APIs usando Laravel, a menudo necesitará convertir sus modelos y relaciones a arrays o JSON. Eloquent incluye métodos convenientes para realizar estas conversiones, así como para controlar qué atributos se incluyen en la representación serializada de sus modelos.

#Serialización de modelos y colecciones

#Serialización a arrays

Para convertir un modelo y sus relaciones cargadas a un array, debe usar el método toArray. Este método es recursivo, por lo que todos los atributos y todas las relaciones (incluidas las relaciones de las relaciones) se convertirán en arrays:

use App\Models\User;

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

return $user->toArray();

El método attributesToArray puede usarse para convertir los atributos de un modelo a un array pero no sus relaciones:

$user = User::first();

return $user->attributesToArray();

También puede convertir colecciones enteras de modelos en arrays llamando al método toArray en la instancia de la colección:

$users = User::all();

return $users->toArray();

#Serialización a JSON

Para convertir un modelo a JSON, debe usar el método toJson. Al igual que toArray, el método toJson es recursivo, por lo que todos los atributos y relaciones se convertirán a JSON. También puede especificar cualquier opción de codificación JSON que sea compatible con PHP:

use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

Alternativamente, puede convertir un modelo o colección a string, lo que llamará automáticamente al método toJson en el modelo o colección:

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

Dado que los modelos y colecciones se convierten a JSON cuando se castea a string, puede devolver objetos Eloquent directamente desde las rutas o controladores de su aplicación. Laravel serializará automáticamente sus modelos y colecciones Eloquent a JSON cuando se devuelvan desde rutas o controladores:

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

#Relaciones

Cuando un modelo Eloquent se convierte a JSON, sus relaciones cargadas se incluirán automáticamente como atributos en el objeto JSON. Además, aunque los métodos de relación de Eloquent se definen usando nombres en "camel case", el atributo JSON de la relación estará en "snake case".

#Ocultar atributos del JSON

A veces puede desear limitar los atributos, como las contraseñas, que se incluyen en la representación en array o JSON de su modelo. Para hacerlo, agregue una propiedad $hidden a su modelo. Los atributos listados en el array de la propiedad $hidden no se incluirán en la representación serializada de su modelo:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Los atributos que deben ocultarse en los arrays.
     *
     * @var array
     */
    protected $hidden = ['password'];
}

Alternativamente, puede usar la propiedad visible para definir una lista de atributos permitidos que deben incluirse en la representación en array y JSON de su modelo. Todos los atributos que no estén presentes en el array $visible se ocultarán cuando el modelo se convierta a array o JSON:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Los atributos que deben ser visibles en los arrays.
     *
     * @var array
     */
    protected $visible = ['first_name', 'last_name'];
}

#Modificar temporalmente la visibilidad de atributos

Si desea hacer visibles algunos atributos que normalmente están ocultos en una instancia concreta de un modelo, puede usar el método makeVisible. El método makeVisible devuelve la instancia del modelo:

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

De igual forma, si desea ocultar algunos atributos que normalmente son visibles, puede usar el método makeHidden.

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

Si desea sobrescribir temporalmente todos los atributos visibles u ocultos, puede usar los métodos setVisible y setHidden respectivamente:

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

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

#Agregar valores al JSON

Ocasionalmente, al convertir modelos a arrays o JSON, puede desear agregar atributos que no tienen una columna correspondiente en su base de datos. Para hacerlo, primero defina un accessor para el valor:

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * Determinar si el usuario es administrador.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

Si desea que el accessor siempre se agregue a las representaciones en array y JSON de su modelo, puede añadir el nombre del atributo a la propiedad appends de su modelo. Tenga en cuenta que los nombres de atributos se suelen referenciar usando su representación serializada en "snake case", aunque el método PHP del accessor esté definido en "camel case":

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Los accessors que se deben agregar a la forma en array del modelo.
     *
     * @var array
     */
    protected $appends = ['is_admin'];
}

Una vez que el atributo ha sido agregado a la lista appends, se incluirá tanto en las representaciones en array como en JSON del modelo. Los atributos en el array appends también respetarán las configuraciones visible y hidden definidas en el modelo.

#Agregar en tiempo de ejecución

En tiempo de ejecución, puede indicar a una instancia del modelo que agregue atributos adicionales usando el método append. O bien, puede usar el método setAppends para sobrescribir todo el array de propiedades agregadas para una instancia dada del modelo:

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

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

#Serialización de fechas

#Personalizar el formato de fecha predeterminado

Puede personalizar el formato de serialización predeterminado sobrescribiendo el método serializeDate. Este método no afecta cómo se formatean sus fechas para almacenarlas en la base de datos:

/**
 * Preparar una 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

Puede personalizar el formato de serialización de atributos de fecha individuales de Eloquent especificando el formato de fecha en las declaraciones de cast del modelo:

protected $casts = [
    'birthday' => 'date:Y-m-d',
    'joined_at' => 'datetime:Y-m-d H:00',
];