Collection Deep Dive - Knowledge of Laravel

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.

Cambios en Laravel 6.0

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

Estructura general actual (Laravel 13)

Referencia: laravel/framework v13.x

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.

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

/**
 * @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

/**
 * @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.

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.

​Objetivo de esta página

​Evolución histórica

​Hasta Laravel 5.8

​Cambios en Laravel 6.0

​Estructura general actual (Laravel 13)

​Generics al estilo PHPDoc y PHPStan

​Notaciones frecuentes

​Cómo se ve en la Collection de Eloquent

​Orden recomendado para leer el código

​1. Empieza por Enumerable

​2. Sigue los métodos comunes en EnumeratesValues

​3. Mira las diferencias entre Collection y LazyCollection

​4. Por último, lee Eloquent\Collection

​Páginas relacionadas

Objetivo de esta página

Evolución histórica

Hasta Laravel 5.8

Cambios en Laravel 6.0

Estructura general actual (Laravel 13)

Generics al estilo PHPDoc y PHPStan

Notaciones frecuentes

Cómo se ve en la Collection de Eloquent

Orden recomendado para leer el código

1. Empieza por `Enumerable`

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

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

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

Páginas relacionadas