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

# Collections Eloquent

> Méthodes propres à Illuminate\Database\Eloquent\Collection et création de collections personnalisées.

## Introduction

Lorsque vous récupérez plusieurs enregistrements avec Eloquent, le résultat est une instance de `Illuminate\Database\Eloquent\Collection`.\
Elle hérite de `Illuminate\Support\Collection`, ce qui permet d'utiliser toutes les méthodes de la collection de base.

```mermaid theme={null}
classDiagram
    class "Illuminate\\Support\\Collection" as SupportCollection
    class "Illuminate\\Database\\Eloquent\\Collection" as EloquentCollection
    SupportCollection <|-- EloquentCollection
```

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

$users = User::where('active', true)->get();

foreach ($users as $user) {
    echo $user->name;
}
```

Il est utile de maîtriser d'abord les [collections](/fr/collections) de base et l'[introduction à Eloquent](/fr/eloquent) pour comprendre ce que les collections Eloquent apportent en plus.

## Méthodes disponibles

`Eloquent\Collection` hérite de toutes les méthodes de la collection de base et ajoute des méthodes spécifiques aux modèles.

### `append` / `withoutAppends` / `setAppends`

Manipulez les attributs additionnels de sérialisation (`appends`) sur toute la collection.

```php theme={null}
$users->append('team');
$users->append(['team', 'is_admin']);

$users = $users->withoutAppends();
$users = $users->setAppends(['is_admin']);
```

### `contains` / `diff` / `except` / `intersect` / `only`

Effectuez des tests d'appartenance, différences, intersections, exclusions et extractions à partir d'instances de modèle ou de clés primaires.

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

$users->contains(1);
$users->contains(User::find(1));

$subset = User::whereIn('id', [1, 2, 3])->get();

$users->diff($subset);
$users->intersect($subset);

$users->except([1, 2, 3]);
$users->only([1, 2, 3]);
```

### `find` / `findOrFail`

Recherchez un modèle par clé primaire dans une collection déjà récupérée.

```php theme={null}
$users = User::all();

$user = $users->find(1);
$user = $users->findOrFail(1);
```

### `fresh`

Récupère à nouveau chaque modèle de la collection dans son état à jour depuis la base.

```php theme={null}
$users = $users->fresh();
$users = $users->fresh('comments');
```

### `load` / `loadMissing`

Chargez en Eager Loading des relations sur une collection déjà récupérée.

```php theme={null}
$users->load(['comments', 'posts']);
$users->load('comments.author');
$users->load(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);

$users->loadMissing(['comments', 'posts']);
$users->loadMissing('comments.author');
$users->loadMissing(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);
```

### `modelKeys`

Retourne la liste des clés primaires des modèles de la collection.

```php theme={null}
$users->modelKeys();
// [1, 2, 3, ...]
```

### `makeVisible` / `makeHidden` / `mergeVisible` / `mergeHidden` / `setVisible` / `setHidden`

Ajustez les attributs visibles/masqués lors de la sérialisation, au niveau de la collection.

```php theme={null}
$users = $users->makeVisible(['address', 'phone_number']);
$users = $users->makeHidden(['address', 'phone_number']);

$users = $users->mergeVisible(['middle_name']);
$users = $users->mergeHidden(['last_login_at']);

$users = $users->setVisible(['id', 'name']);
$users = $users->setHidden(['email', 'password', 'remember_token']);
```

### `partition`

Divise la collection en deux `Eloquent\Collection` selon une condition ; l'enveloppe est un `Illuminate\Support\Collection`.

```php theme={null}
$partition = $users->partition(fn ($user) => $user->age > 18);

dump($partition::class);    // Illuminate\Support\Collection
dump($partition[0]::class); // Illuminate\Database\Eloquent\Collection
dump($partition[1]::class); // Illuminate\Database\Eloquent\Collection
```

### `toQuery`

Construit une requête `whereIn` sur les clés primaires des modèles récupérés, utile pour des mises à jour ou suppressions en masse.

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

// Récupère d'abord les utilisateurs correspondant au critère
$vipUsers = User::where('status', 'VIP')->get();

// Met à jour en masse uniquement les modèles ciblés
$vipUsers->toQuery()->update([
    'status' => 'Administrator',
]);
```

<Tip>
  Plutôt que boucler avec des `save()` individuels, convertir en requête en masse via `toQuery()` améliore à la fois les performances et la lisibilité en production.
</Tip>

### `unique`

Supprime les modèles en double partageant la même clé primaire.

```php theme={null}
$users = $users->unique();
```

## Conversion vers une collection de base

`collapse`, `flatten`, `flip`, `keys`, `pluck` et `zip` retournent `Illuminate\Support\Collection`.\
De même, si le résultat de `map` ne contient plus de modèles Eloquent, il est converti en collection de base.

## Collections personnalisées

Pour utiliser une classe de collection propre à un modèle, la méthode la plus claire consiste à utiliser l'attribut `#[CollectedBy]`.

### Attribut `#[CollectedBy]` (recommandé)

```php theme={null}
<?php

namespace App\Models;

use App\Support\UserCollection;
use Illuminate\Database\Eloquent\Attributes\CollectedBy;
use Illuminate\Database\Eloquent\Model;

#[CollectedBy(UserCollection::class)]
class User extends Model
{
    // ...
}
```

### Méthode `newCollection()` (alternative)

```php theme={null}
<?php

namespace App\Models;

use App\Support\UserCollection;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    public function newCollection(array $models = []): Collection
    {
        $collection = new UserCollection($models);

        if (Model::isAutomaticallyEagerLoadingRelationships()) {
            $collection->withRelationshipAutoloading();
        }

        return $collection;
    }
}
```

En définissant `newCollection()` ou `#[CollectedBy]`, la collection personnalisée sera retournée là où `Eloquent\Collection` l'était habituellement.\
Pour l'appliquer à tous les modèles, définissez `newCollection()` dans un modèle de base commun.

## Pages associées

<Card title="Collections" icon="list" href="/fr/collections">
  Prenez d'abord connaissance des opérations de base de `Illuminate\\Support\\Collection`.
</Card>

<Card title="Introduction à Eloquent" icon="database" href="/fr/eloquent">
  Maîtrisez d'abord les bases des modèles et des requêtes avant d'utiliser les collections Eloquent.
</Card>


## Related topics

- [Eloquent API Resources](/fr/eloquent-resources.md)
- [Réponses](/fr/responses.md)
- [Trait Dumpable](/fr/advanced/dumpable.md)
- [Messages d'ordre supérieur des collections](/fr/advanced/higher-order-messages.md)
- [Collections](/fr/collections.md)