Collection Deep Dive

Illustra l’implementazione delle Laravel Collection dal punto di vista di storia, struttura delle classi, generics in PHPDoc e come leggerne il codice.

​

Scopo di questa pagina

Questa pagina non spiega come usare collect(): fornisce una mappa per leggere il codice di implementazione del core di Laravel.

Il pubblico è chi conosce già l’elenco dei metodi di Collection e vuole ora capire “perché questo design”.

​

Evoluzione storica

La struttura di Collection è stata riorganizzata in modo significativo con l’introduzione di LazyCollection.

​

Fino a Laravel 5.8

• Illuminate\Support\Collection
• Illuminate\Database\Eloquent\Collection (estende Collection)

A questo punto non esistono LazyCollection, Enumerable e EnumeratesValues.

• Collection.php in 5.8
• Eloquent Collection.php in 5.8

​

Modifiche in Laravel 6.0

In concomitanza con l’aggiunta di LazyCollection, l’API comune è stata separata in Enumerable (interfaccia) ed EnumeratesValues (trait).

• LazyCollection.php in 6.x
• Enumerable.php in 6.x
• EnumeratesValues.php in 6.x

​

Struttura complessiva attuale (Laravel 13)

Riferimento: laravel/framework v13.x

• Collection.php
• LazyCollection.php
• EnumeratesValues.php
• Enumerable.php
• Eloquent Collection.php

Attualmente il path fisico dei file è src/Illuminate/Collections/*, ma il namespace resta Illuminate\\Support. Quando leggi il codice, tieni distinti “path” e “namespace”.

​

Generics stile PHPDoc / PHPStan

PHP di per sé non ha i generics. Nonostante ciò, attorno a Collection si esprime un’informazione di tipo forte tramite PHPDoc.

Ci sono due obiettivi principali.

• Ottenere un autocompletamento accurato nell’IDE
• Aumentare la precisione di analizzatori statici come PHPStan / Larastan

​

Notazioni ricorrenti

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

Notazione	Significato
@template TKey of array-key	Vincola il tipo della chiave a int|string
@template-covariant TValue	Tratta il tipo del valore come covariante (facilita la sostituzione sicura con tipi più specifici)
@implements ...<TKey, TValue>	Passa gli argomenti di tipo all’interfaccia implementata
@extends ...<TKey, TModel>	Dichiara gli argomenti di tipo per l’ereditarietà dalla classe padre
@use ...<TKey, TValue>	Dichiara gli argomenti di tipo quando si applica il trait

​

Come appare nella Collection di Eloquent

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

TValue viene specializzato in TModel, quindi l’inferenza di tipo di map(), filter() e simili risulta più orientata ai modelli Eloquent.

​

Ordine con cui leggere l’implementazione

​

1. Parti da Enumerable come punto d’ingresso

Prima di tutto, cattura “qual è il contract che offre”. Se qui memorizzi l’elenco dei metodi, la successiva lettura dell’implementazione sarà più veloce.

​

2. Segui i metodi comuni in EnumeratesValues

Gran parte della logica comune — map, filter, reduce — vive qui. Se poi guardi solo le differenze tra Collection e LazyCollection, salterai meno passaggi.

​

3. Osserva le differenze tra Collection e LazyCollection

• Collection: valutazione immediata mantenendo un array
• LazyCollection: valutazione pigra usando Generator

Anche a parità di nome del metodo cambiano il tempo di valutazione e le caratteristiche di memoria.

​

4. Da ultimo leggi Eloquent\Collection

Concentrati sulle estensioni per insiemi di modelli come find, load, modelKeys. Se prima capisci la Collection di base, le intenzioni saranno più chiare.

Per approfondire un singolo metodo, segui l’ordine: dichiarazione in Enumerable → corpo in EnumeratesValues → eventuali override in Collection / LazyCollection. Non ti perderai.

​

Pagine correlate

• Collezioni
• Higher-order messages delle collection
• Trait Macroable