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.

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 de base et l’introduction à 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.

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

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.

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

$users = $users->fresh();
$users = $users->fresh('comments');

​

load / loadMissing

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

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

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

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

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

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',
]);

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.

​

unique

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

$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

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

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

Collections

Prenez d’abord connaissance des opérations de base de Illuminate\\Support\\Collection.

Introduction à Eloquent

Maîtrisez d’abord les bases des modèles et des requêtes avant d’utiliser les collections Eloquent.