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

# Collection Deep Dive

> Découvrez l'implémentation des Collections Laravel sous les angles de l'histoire, de la structure des classes, des Generics PHPDoc et de la manière de la parcourir.

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

* [Collection.php en 5.8](https://github.com/laravel/framework/blob/5.8/src/Illuminate/Support/Collection.php)
* [Eloquent Collection.php en 5.8](https://github.com/laravel/framework/blob/5.8/src/Illuminate/Database/Eloquent/Collection.php)

### Changements en Laravel 6.0

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

* [LazyCollection.php en 6.x](https://github.com/laravel/framework/blob/6.x/src/Illuminate/Support/LazyCollection.php)
* [Enumerable.php en 6.x](https://github.com/laravel/framework/blob/6.x/src/Illuminate/Support/Enumerable.php)
* [EnumeratesValues.php en 6.x](https://github.com/laravel/framework/blob/6.x/src/Illuminate/Support/Traits/EnumeratesValues.php)

## Structure globale actuelle (Laravel 13)

> Référence : [laravel/framework v13.x](https://github.com/laravel/framework/tree/13.x/src/Illuminate)

```mermaid theme={null}
classDiagram
    class Enumerable {
      <<interface>>
    }
    class EnumeratesValues {
      <<trait>>
    }
    class Collection
    class LazyCollection
    class EloquentCollection

    Collection ..|> Enumerable : implements
    LazyCollection ..|> Enumerable : implements
    Collection ..> EnumeratesValues : use
    LazyCollection ..> EnumeratesValues : use
    EloquentCollection --|> Collection : extends

    note for Enumerable "Contrat de<br>l'API commune"
    note for EnumeratesValues "Implémentation<br>des méthodes communes"
    note for Collection "Évaluation immédiate<br>en mémoire"
    note for LazyCollection "Évaluation paresseuse<br>basée sur Generator"
    note for EloquentCollection "Extension pour les<br>modèles Eloquent"
```

* [Collection.php](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Collections/Collection.php)
* [LazyCollection.php](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Collections/LazyCollection.php)
* [EnumeratesValues.php](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Collections/Traits/EnumeratesValues.php)
* [Enumerable.php](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Collections/Enumerable.php)
* [Eloquent Collection.php](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Eloquent/Collection.php)

<Info>
  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 ».
</Info>

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

```php theme={null}
/**
 * @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

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

<Tip>
  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.
</Tip>

## Pages associées

* [Collections](/fr/collections)
* [Messages d'ordre supérieur de Collection](/fr/advanced/higher-order-messages)
* [Trait Macroable](/fr/advanced/macroable)


## Related topics

- [Collections](/fr/collections.md)
- [Collections Eloquent](/fr/eloquent-collections.md)
- [Messages d'ordre supérieur des collections](/fr/advanced/higher-order-messages.md)
- [Laravel Console Starter](/fr/packages/laravel-console-starter/index.md)
- [Laravel Bluesky](/fr/packages/laravel-bluesky/index.md)