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

> Explica la implementación de Laravel Collection desde la perspectiva de su historia, la estructura de clases, los Generics de PHPDoc y cómo leer su código.

## Objetivo de esta página

Esta página no cubre cómo usar `collect()`, sino que ofrece un mapa para leer el código de implementación del propio Laravel.

Está dirigida a quienes ya conocen la lista de métodos de `Collection` y quieren entender por qué el diseño es como es.

## Evolución histórica

La estructura de Collection se reorganizó de forma importante con la introducción de `LazyCollection`.

### Hasta Laravel 5.8

* `Illuminate\Support\Collection`
* `Illuminate\Database\Eloquent\Collection` (extiende `Collection`)

En ese momento no existían `LazyCollection`, `Enumerable` ni `EnumeratesValues`.

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

### Cambios en Laravel 6.0

Con la incorporación de `LazyCollection`, la API común se separó en `Enumerable` (interfaz) y `EnumeratesValues` (trait).

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

## Estructura general actual (Laravel 13)

> Referencia: [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 "Contrato<br>de la API común"
    note for EnumeratesValues "Cuerpo de la<br>implementación común"
    note for Collection "Evaluación inmediata<br>en memoria"
    note for LazyCollection "Evaluación perezosa<br>basada en Generator"
    note for EloquentCollection "Extensión para<br>modelos 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)
* [Collection.php de Eloquent](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Eloquent/Collection.php)

<Info>
  La ruta real actual de los archivos es `src/Illuminate/Collections/*`, pero el namespace se mantiene como `Illuminate\Support`. Al leer el código, ten en cuenta que la «ruta» y el «namespace» son cosas distintas.
</Info>

## Generics al estilo PHPDoc y PHPStan

PHP nativo no tiene genéricos. Aun así, en el código de Collection se expresa información de tipos muy rica mediante PHPDoc.

Persigue dos objetivos principales:

* Que el autocompletado del IDE sea preciso.
* Aumentar la precisión de los analizadores estáticos como PHPStan / Larastan.

### Notaciones frecuentes

```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;
}
```

| Notación                        | Significado                                                                                           |
| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `@template TKey of array-key`   | Restringe el tipo de la clave a `int\|string`.                                                        |
| `@template-covariant TValue`    | Trata el tipo del valor como covariante (permite sustituirlo con seguridad por un tipo más concreto). |
| `@implements ...<TKey, TValue>` | Pasa los tipos genéricos a la interfaz implementada.                                                  |
| `@extends ...<TKey, TModel>`    | Declara los argumentos de tipo al heredar de una clase padre.                                         |
| `@use ...<TKey, TValue>`        | Declara los argumentos de tipo al aplicar un trait.                                                   |

### Cómo se ve en la Collection de Eloquent

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

Como `TValue` se concreta como `TModel`, la inferencia de tipos de `map()`, `filter()`, etc., se refuerza orientándose a los modelos Eloquent.

## Orden recomendado para leer el código

### 1. Empieza por `Enumerable`

Primero, entiende «qué contrato define». Conocer la lista de métodos aquí acelera la lectura del resto de la implementación.

### 2. Sigue los métodos comunes en `EnumeratesValues`

Muchos métodos comunes como `map`, `filter` o `reduce` están aquí. Si dejas para después solo las diferencias entre `Collection` y `LazyCollection`, evitarás lecturas redundantes.

### 3. Mira las diferencias entre `Collection` y `LazyCollection`

* `Collection`: guarda un array y evalúa de forma inmediata.
* `LazyCollection`: usa un `Generator` y evalúa de forma perezosa.

Aunque los métodos se llamen igual, el momento de evaluación y las características de memoria cambian.

### 4. Por último, lee `Eloquent\Collection`

Céntrate en las extensiones específicas para conjuntos de modelos como `find`, `load` o `modelKeys`. Si la lees después de comprender la `Collection` base, entenderás mejor su intención.

<Tip>
  Cuando quieras profundizar en un único método, sigue este orden para no perderte: la declaración en `Enumerable` → el cuerpo en `EnumeratesValues` → si hay override en `Collection` / `LazyCollection`.
</Tip>

## Páginas relacionadas

* [Colecciones](/es/collections)
* [Mensajes de orden superior en colecciones](/es/advanced/higher-order-messages)
* [Trait Macroable](/es/advanced/macroable)


## Related topics

- [Laravel Bluesky](/es/packages/laravel-bluesky/index.md)
- [Laravel Console Starter](/es/packages/laravel-console-starter/index.md)
- [LINE SDK for Laravel](/es/packages/laravel-line-sdk/index.md)
- [Laravel AI SDK](/es/ai-sdk.md)
- [Colecciones Eloquent](/es/eloquent-collections.md)