Sérialisation Eloquent

Convertir des modèles Eloquent en JSON/tableau, contrôler la visibilité des attributs, ajouter des attributs et personnaliser le format des dates.

​

Introduction

Lorsque vous construisez une API avec Laravel, il est fréquent de convertir un modèle et ses relations en tableau ou en JSON. Eloquent propose des méthodes pratiques pour ces conversions ainsi qu’un contrôle fin des attributs à inclure dans la représentation sérialisée.

Pour une sérialisation JSON plus robuste, consultez la documentation des Eloquent API Resources.

​

Modèles et tableaux

​

Vers un tableau

Utilisez toArray pour convertir le modèle et ses relations chargées en tableau. La méthode fonctionne récursivement : tous les attributs et toutes les relations (y compris les relations imbriquées) sont convertis.

use App\Models\User;

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

return $user->toArray();

attributesToArray ne convertit que les attributs, sans les relations.

$user = User::first();

return $user->attributesToArray();

Pour une collection entière, appelez toArray sur la collection.

$users = User::all();

return $users->toArray();

​

Vers du JSON

toJson convertit le modèle en JSON. Comme toArray, elle fonctionne récursivement. Vous pouvez passer les options d’encodage JSON de PHP.

use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

Le cast en chaîne appelle automatiquement toJson.

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

Les modèles et collections étant convertis en JSON à la conversion en chaîne, vous pouvez les retourner directement depuis les routes ou contrôleurs. Laravel sérialise automatiquement en JSON les modèles et collections Eloquent retournés.

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

​

Relations

Lors de la conversion en JSON, les relations chargées sont incluses automatiquement. Les méthodes de relation sont en camelCase, mais leurs clés JSON sont en snake_case.

​

Contrôle de la visibilité des attributs

​

Masquer des attributs

Vous voudrez limiter l’exposition de certains attributs (mot de passe, etc.). Utilisez l’attribut Hidden. Les attributs listés ne figurent pas dans la représentation sérialisée.

<?php

namespace App\Models;

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

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

Pour cacher une relation, ajoutez le nom de la méthode de relation à Hidden.

​

Rendre visibles

Visible définit une liste d’autorisation. Tout attribut non listé est masqué.

<?php

namespace App\Models;

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

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

​

Rendre visibles / masquer temporairement

Pour rendre visible un attribut normalement masqué, utilisez makeVisible ou mergeVisible.

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

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

À l’inverse, makeHidden ou mergeHidden masquent des attributs.

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

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

setVisible et setHidden remplacent complètement les listes.

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

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

​

Attributs supplémentaires

Vous pouvez ajouter à la sérialisation des attributs sans colonne correspondante en base. Définissez d’abord un accesseur.

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * Indique si l'utilisateur est administrateur.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

Pour l’inclure automatiquement, utilisez l’attribut Appends sur le modèle. La méthode PHP est en camelCase, mais l’attribut sérialisé utilise le snake_case.

<?php

namespace App\Models;

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

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

Un attribut listé dans appends figure à la fois dans le tableau et le JSON, tout en respectant visible/hidden.

​

Ajout à l’exécution

Utilisez append, mergeAppends ou setAppends à l’exécution.

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

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

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

Retirez tous les appends avec withoutAppends.

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

​

Sérialisation des dates

​

Format par défaut

Redéfinissez serializeDate pour changer le format par défaut. Cela n’affecte pas le format de stockage en base.

/**
 * Prépare une date pour la sérialisation tableau/JSON.
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

​

Format par attribut

Précisez le format dans la déclaration de cast.

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