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

> 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](https://github.com/laravel/framework/blob/5.8/src/Illuminate/Support/Collection.php)
* [Eloquent Collection.php in 5.8](https://github.com/laravel/framework/blob/5.8/src/Illuminate/Database/Eloquent/Collection.php)

### 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](https://github.com/laravel/framework/blob/6.x/src/Illuminate/Support/LazyCollection.php)
* [Enumerable.php in 6.x](https://github.com/laravel/framework/blob/6.x/src/Illuminate/Support/Enumerable.php)
* [EnumeratesValues.php in 6.x](https://github.com/laravel/framework/blob/6.x/src/Illuminate/Support/Traits/EnumeratesValues.php)

## Struttura complessiva attuale (Laravel 13)

> Riferimento: [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 "Contract<br>dell'API comune"
    note for EnumeratesValues "Corpo dell'implementazione<br>dei metodi comuni"
    note for Collection "Valutazione immediata<br>in memoria"
    note for LazyCollection "Valutazione pigra<br>basata su Generator"
    note for EloquentCollection "Estensione dedicata<br>ai modelli 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>
  Attualmente il path fisico dei file è `src/Illuminate/Collections/*`, ma il namespace resta `Illuminate\\Support`. Quando leggi il codice, tieni distinti "path" e "namespace".
</Info>

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

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

| 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

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

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

## Pagine correlate

* [Collezioni](/it/collections)
* [Higher-order messages delle collection](/it/advanced/higher-order-messages)
* [Trait Macroable](/it/advanced/macroable)


## Related topics

- [Higher-order messages delle collection](/it/advanced/higher-order-messages.md)
- [Laravel Bluesky](/it/packages/laravel-bluesky/index.md)
- [Laravel Console Starter](/it/packages/laravel-console-starter/index.md)
- [Laravel AI SDK](/it/ai-sdk.md)
- [LINE SDK for Laravel](/it/packages/laravel-line-sdk/index.md)