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

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

<Info>
  Pour une sérialisation JSON plus robuste, consultez la documentation des [Eloquent API Resources](./eloquent-resources).
</Info>

## Modèles et tableaux

### Vers un tableau

Utilisez `toArray` pour convertir le modèle et ses [relations](./eloquent-relationships) 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.

```php theme={null}
use App\Models\User;

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

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

`attributesToArray` ne convertit que les attributs, sans les relations.

```php theme={null}
$user = User::first();

return $user->attributesToArray();
```

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

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

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

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

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

namespace App\Models;

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

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

<Info>
  Pour cacher une relation, ajoutez le nom de la méthode de relation à `Hidden`.
</Info>

### Rendre visibles

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

```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
{
    // ...
}
```

### Rendre visibles / masquer temporairement

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

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

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

À l'inverse, `makeHidden` ou `mergeHidden` masquent des attributs.

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

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

`setVisible` et `setHidden` remplacent complètement les listes.

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

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

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

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

```php theme={null}
/**
 * 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](./eloquent-mutators#attribute-casting).

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


## Related topics

- [Collections Eloquent](/fr/eloquent-collections.md)
- [Accesseurs, mutateurs et casts Eloquent](/fr/eloquent-mutators.md)
- [Attributs PHP](/fr/advanced/php-attributes.md)
- [Laravel Scout](/fr/scout.md)
- [Événements et listeners](/fr/events.md)