Eloquent-Collections

Erläutert die speziellen Methoden von Illuminate\Database\Eloquent\Collection und die Erstellung eigener Collections.

​

Einführung

Wenn Sie mit Eloquent mehrere Modelle abfragen, erhalten Sie das Ergebnis als Illuminate\Database\Eloquent\Collection. Da diese Klasse von Illuminate\Support\Collection erbt, stehen alle Methoden der Basis-Collection zur Verfügung.

use App\Models\User;

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

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

Machen Sie sich zunächst mit der grundlegenden Collection und der Einführung in Eloquent vertraut – so verstehen Sie die Erweiterungen der Eloquent-Collection leichter.

​

Verfügbare Methoden

Eloquent\Collection erbt alle Methoden der Basis-Collection und ergänzt zusätzliche, modellorientierte Methoden.

​

append / withoutAppends / setAppends

Verwaltet die bei der Serialisierung angehängten Attribute (Appends) für die gesamte Collection.

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

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

​

contains / diff / except / intersect / only

Führt anhand von Modellinstanzen oder Primärschlüsseln Enthaltensein, Differenz, Schnittmenge, Ausschluss oder Auswahl durch.

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

Sucht in einer bereits geladenen Collection ein Modell über den Primärschlüssel.

$users = User::all();

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

​

fresh

Lädt alle Modelle der Collection erneut mit ihrem aktuellen Datenbankzustand.

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

​

load / loadMissing

Lädt Relationen einer bereits geladenen Collection nachträglich per Eager Loading.

$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

Liefert die Primärschlüssel aller Modelle in der Collection.

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

​

makeVisible / makeHidden / mergeVisible / mergeHidden / setVisible / setHidden

Ermöglicht es, die bei der Serialisierung sichtbaren bzw. verborgenen Attribute auf Collection-Ebene anzupassen.

$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

Teilt anhand einer Bedingung in zwei Eloquent\Collection-Objekte auf; der äußere Container ist eine 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

Erzeugt eine whereIn-Abfrage über die Primärschlüssel der geladenen Modelle, mit der Sie zum Beispiel Massenaktualisierungen oder -löschungen durchführen können.

use App\Models\User;

// Zunächst alle passenden Nutzer laden
$vipUsers = User::where('status', 'VIP')->get();

// Nur die Modelle der Collection in einer Abfrage aktualisieren
$vipUsers->toQuery()->update([
    'status' => 'Administrator',
]);

Statt einer Schleife mit einzelnen save()-Aufrufen bringt die Umwandlung in eine gebündelte Query per toQuery() in der Praxis oft bessere Performance und lesbareren Code.

​

unique

Entfernt Modelle mit doppeltem Primärschlüssel.

$users = $users->unique();

​

Umwandlung in eine Basis-Collection

Die Methoden collapse, flatten, flip, keys, pluck und zip liefern eine Illuminate\Support\Collection zurück. Enthält das Ergebnis eines map-Aufrufs keine Eloquent-Modelle, wird ebenfalls in eine Basis-Collection konvertiert.

​

Eigene Collections

Möchten Sie für ein Modell eine dedizierte Collection-Klasse verwenden, ist das Attribut #[CollectedBy] die klarste Möglichkeit.

​

Attribut #[CollectedBy] (empfohlen)

<?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
{
    // ...
}

​

Methode newCollection() (Alternative)

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

Wenn Sie newCollection() oder #[CollectedBy] definieren, wird an Stellen, an denen normalerweise eine Eloquent\Collection zurückgegeben würde, Ihre eigene Collection verwendet. Sollen alle Modelle davon profitieren, definieren Sie newCollection() in einer gemeinsamen Basisklasse.

​

Verwandte Seiten

Collections

Vertiefen Sie zuerst die Grundlagen von Illuminate\Support\Collection.

Einführung in Eloquent

Frischen Sie Modelle und Query-Grundlagen auf, bevor Sie mit Eloquent-Collections weiterarbeiten.