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.
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();
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);
toJson.
return (string) User::find(1);
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();
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',
);
}
}
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
{
// ...
}
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();
withoutAppends.
return $user->withoutAppends()->toArray();
Sérialisation des dates
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');
}
protected function casts(): array
{
return [
'birthday' => 'date:Y-m-d',
'joined_at' => 'datetime:Y-m-d H:00',
];
}
