Collection Deep Dive - Knowledge of Laravel

Objectif de cette page

Cette page ne vous apprend pas à utiliser collect(), mais vous fournit une carte pour lire le code d’implémentation du cœur de Laravel. Le public visé est celui qui connaît déjà la liste des méthodes de Collection et souhaite maintenant comprendre « pourquoi cette conception ».

Évolution historique

La structure des Collections a été profondément réorganisée lors de l’introduction de LazyCollection.

Jusqu’à Laravel 5.8

Illuminate\Support\Collection
Illuminate\Database\Eloquent\Collection (hérite de Collection)

À cette époque, LazyCollection, Enumerable et EnumeratesValues n’existent pas.

Changements en Laravel 6.0

Avec l’ajout de LazyCollection, l’API commune a été séparée dans Enumerable (interface) et EnumeratesValues (trait).

Structure globale actuelle (Laravel 13)

Référence : laravel/framework v13.x

Le chemin réel des fichiers actuels est src/Illuminate/Collections/*, mais le namespace reste Illuminate\Support. En lisant le code, prenez garde à bien distinguer « chemin » et « namespace ».

PHPDoc et Generics de style PHPStan

PHP lui-même n’a pas de Generics. Malgré cela, autour des Collections, des informations de type puissantes sont exprimées via PHPDoc. Il y a deux objectifs principaux :

Rendre la complétion IDE précise
Améliorer la précision de l’analyse statique de PHPStan / Larastan, etc.

Notations courantes

/**
 * @template TKey of array-key
 * @template-covariant TValue
 * @implements \Illuminate\Support\Enumerable<TKey, TValue>
 */
class Collection implements Enumerable
{
    /**
     * @use \Illuminate\Support\Traits\EnumeratesValues<TKey, TValue>
     */
    use EnumeratesValues;
}

Notation	Signification
`@template TKey of array-key`	Contraint le type de clé à `int\|string`
`@template-covariant TValue`	Traite le type de valeur comme covariant (facilite le remplacement sûr vers un type plus spécifique)
`@implements ...<TKey, TValue>`	Passe des arguments de type à l’interface implémentée
`@extends ...<TKey, TModel>`	Déclare les arguments de type lors de l’héritage d’une classe parente
`@use ...<TKey, TValue>`	Déclare les arguments de type lors de l’application d’un trait

Aperçu dans Eloquent Collection

/**
 * @template TKey of array-key
 * @template TModel of \Illuminate\Database\Eloquent\Model
 * @extends \Illuminate\Support\Collection<TKey, TModel>
 */
class Collection extends BaseCollection
{
}

TValue est concrétisé en TModel, ce qui renforce l’inférence de type de map(), filter(), etc. orientée modèles Eloquent.

Ordre pour lire l’implémentation

1. Commencer par `Enumerable`

Saisissez d’abord « quel contrat est fourni ». En connaissant la liste des méthodes ici, la lecture des implémentations suivantes sera plus rapide.

2. Suivre les méthodes communes dans `EnumeratesValues`

La majorité de la logique commune se trouve ici : map, filter, reduce, etc. En ne regardant ensuite que les différences entre Collection et LazyCollection, vous éviterez de vous perdre.

3. Examiner les différences entre `Collection` et `LazyCollection`

Collection : conserve un tableau et évalue immédiatement
LazyCollection : utilise Generator pour une évaluation paresseuse

Même à nom identique, la temporalité d’évaluation et les caractéristiques mémoire diffèrent.

4. Lire enfin `Eloquent\Collection`

Concentrez-vous sur les extensions destinées aux ensembles de modèles : find, load, modelKeys, etc. La lecture après avoir compris la Collection de base fait ressortir plus clairement l’intention.

Pour analyser une méthode en profondeur, suivez cet ordre : déclaration dans Enumerable → corps dans EnumeratesValues → surcharges éventuelles dans Collection / LazyCollection. Vous ne vous perdrez pas.

​Objectif de cette page

​Évolution historique

​Jusqu’à Laravel 5.8

​Changements en Laravel 6.0

​Structure globale actuelle (Laravel 13)

​PHPDoc et Generics de style PHPStan

​Notations courantes

​Aperçu dans Eloquent Collection

​Ordre pour lire l’implémentation

​1. Commencer par Enumerable

​2. Suivre les méthodes communes dans EnumeratesValues

​3. Examiner les différences entre Collection et LazyCollection

​4. Lire enfin Eloquent\Collection

​Pages associées

Objectif de cette page

Évolution historique

Jusqu’à Laravel 5.8

Changements en Laravel 6.0

Structure globale actuelle (Laravel 13)

PHPDoc et Generics de style PHPStan

Notations courantes

Aperçu dans Eloquent Collection

Ordre pour lire l’implémentation

1. Commencer par `Enumerable`

2. Suivre les méthodes communes dans `EnumeratesValues`

3. Examiner les différences entre `Collection` et `LazyCollection`

4. Lire enfin `Eloquent\Collection`

Pages associées