Collezioni Eloquent

Metodi dedicati di Illuminate\Database\Eloquent\Collection e come creare collezioni personalizzate.

​

Introduzione

Quando recuperi più modelli con Eloquent, il risultato viene restituito come Illuminate\Database\Eloquent\Collection.
Poiché estende Illuminate\Support\Collection, puoi usare i metodi della collezione di base così come sono.

use App\Models\User;

$users = User::where('active', true)->get();

foreach ($users as $user) {
    echo $user->name;
}

Padroneggiare prima le Collezioni di base e l’Introduzione a Eloquent rende più facile capire le estensioni offerte dalle collezioni Eloquent.

​

Metodi disponibili

Eloquent\Collection eredita tutti i metodi della collezione di base e aggiunge inoltre metodi specifici per i modelli.

​

append / withoutAppends / setAppends

Puoi manipolare gli attributi aggiuntivi (appends) usati in fase di serializzazione a livello dell’intera collezione.

$users->append('team');
$users->append(['team', 'is_admin']);

$users = $users->withoutAppends();
$users = $users->setAppends(['is_admin']);

​

contains / diff / except / intersect / only

Prendendo come riferimento istanze di modelli o chiavi primarie, esegui verifica di appartenenza, differenza, intersezione, esclusione ed estrazione.

use App\Models\User;

$users->contains(1);
$users->contains(User::find(1));

$subset = User::whereIn('id', [1, 2, 3])->get();

$users->diff($subset);
$users->intersect($subset);

$users->except([1, 2, 3]);
$users->only([1, 2, 3]);

​

find / findOrFail

Cerca un modello per chiave primaria nella collezione già recuperata.

$users = User::all();

$user = $users->find(1);
$user = $users->findOrFail(1);

​

fresh

Ricarica ciascun modello della collezione con lo stato più recente dal database.

$users = $users->fresh();
$users = $users->fresh('comments');

​

load / loadMissing

Puoi caricare le relazioni con eager loading su una collezione già recuperata.

$users->load(['comments', 'posts']);
$users->load('comments.author');
$users->load(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);

$users->loadMissing(['comments', 'posts']);
$users->loadMissing('comments.author');
$users->loadMissing(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);

​

modelKeys

Ottiene l’elenco delle chiavi primarie dei modelli nella collezione.

$users->modelKeys();
// [1, 2, 3, ...]

​

makeVisible / makeHidden / mergeVisible / mergeHidden / setVisible / setHidden

Puoi regolare a livello di collezione gli attributi visibili e nascosti in fase di serializzazione.

$users = $users->makeVisible(['address', 'phone_number']);
$users = $users->makeHidden(['address', 'phone_number']);

$users = $users->mergeVisible(['middle_name']);
$users = $users->mergeHidden(['last_login_at']);

$users = $users->setVisible(['id', 'name']);
$users = $users->setHidden(['email', 'password', 'remember_token']);

​

partition

Divide in due Eloquent\Collection in base alla condizione; il contenitore esterno viene restituito come Illuminate\Support\Collection.

$partition = $users->partition(fn ($user) => $user->age > 18);

dump($partition::class);    // Illuminate\Support\Collection
dump($partition[0]::class); // Illuminate\Database\Eloquent\Collection
dump($partition[1]::class); // Illuminate\Database\Eloquent\Collection

​

toQuery

Crea una query whereIn sulle chiavi primarie dei modelli recuperati; puoi usarla per aggiornamenti o eliminazioni in blocco.

use App\Models\User;

// Prima recupera gli utenti che soddisfano la condizione
$vipUsers = User::where('status', 'VIP')->get();

// Aggiorna in blocco solo gli utenti della collezione
$vipUsers->toQuery()->update([
    'status' => 'Administrator',
]);

Rispetto a un ciclo di save() individuali, convertire in una query in blocco con toQuery() permette di conciliare più facilmente prestazioni e leggibilità nel funzionamento reale.

​

unique

Rimuove i modelli duplicati che condividono la stessa chiave primaria.

$users = $users->unique();

​

Conversione da collezione Eloquent a collezione di base

collapse, flatten, flip, keys, pluck e zip restituiscono Illuminate\Support\Collection.
Inoltre, se il risultato di map non contiene modelli Eloquent, viene convertito in una collezione di base.

​

Collezioni personalizzate

Se vuoi usare una classe di collezione dedicata a un modello, il metodo più chiaro consiste nell’usare l’attributo #[CollectedBy].

​

Attributo #[CollectedBy] (consigliato)

<?php

namespace App\Models;

use App\Support\UserCollection;
use Illuminate\Database\Eloquent\Attributes\CollectedBy;
use Illuminate\Database\Eloquent\Model;

#[CollectedBy(UserCollection::class)]
class User extends Model
{
    // ...
}

​

Metodo newCollection() (alternativa)

<?php

namespace App\Models;

use App\Support\UserCollection;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    public function newCollection(array $models = []): Collection
    {
        $collection = new UserCollection($models);

        if (Model::isAutomaticallyEagerLoadingRelationships()) {
            $collection->withRelationshipAutoloading();
        }

        return $collection;
    }
}

Definendo newCollection() oppure #[CollectedBy], nei contesti in cui normalmente verrebbe restituita Eloquent\Collection verrà invece restituita la collezione personalizzata.
Se vuoi applicarlo a tutti i modelli, definisci newCollection() in un modello base comune.

​

Pagine correlate

Collezioni

Rivedi prima le operazioni di base di Illuminate\\Support\\Collection.

Introduzione a Eloquent

Ripassa le basi di modelli e query prima di usare le collezioni Eloquent.