Colecciones Eloquent

Explicamos los métodos específicos de Illuminate\Database\Eloquent\Collection y cómo crear colecciones personalizadas.

​

Introducción

Cuando obtienes varios modelos con Eloquent, el resultado se devuelve como Illuminate\Database\Eloquent\Collection.
Como extiende Illuminate\Support\Collection, puedes usar sin cambios todos los métodos de la colección base.

use App\Models\User;

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

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

Conviene tener claros los conceptos base de Colecciones y de Introducción a Eloquent para entender mejor las extensiones que aporta la colección de Eloquent.

​

Métodos disponibles

Eloquent\Collection hereda todos los métodos de la colección base y añade además métodos específicos para modelos.

​

append / withoutAppends / setAppends

Permite manipular los atributos añadidos (appends) durante la serialización para toda la colección.

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

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

​

contains / diff / except / intersect / only

Realiza comprobaciones de pertenencia, diferencia, intersección, exclusión y extracción, basadas en instancias de modelo o claves primarias.

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

Busca en la colección ya obtenida por clave primaria.

$users = User::all();

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

​

fresh

Vuelve a obtener cada modelo de la colección con su estado más reciente de la base de datos.

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

​

load / loadMissing

Realiza eager loading de relaciones sobre una colección ya obtenida.

$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

Devuelve la lista de claves primarias de los modelos de la colección.

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

​

makeVisible / makeHidden / mergeVisible / mergeHidden / setVisible / setHidden

Permite ajustar por colección qué atributos son visibles u ocultos durante la serialización.

$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 la colección en dos Eloquent\Collection según una condición y devuelve por fuera una 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

Genera una consulta whereIn sobre las claves primarias de los modelos obtenidos, útil para actualizar o eliminar en bloque.

use App\Models\User;

// Primero obtiene los usuarios que cumplen la condición
$vipUsers = User::where('status', 'VIP')->get();

// Actualiza en bloque solo los usuarios de la colección
$vipUsers->toQuery()->update([
    'status' => 'Administrator',
]);

Convertir a una única consulta con toQuery() en lugar de recorrer y llamar a save() individualmente ofrece un buen equilibrio entre rendimiento y legibilidad en la práctica.

​

unique

Elimina los modelos duplicados con la misma clave primaria.

$users = $users->unique();

​

Conversión de una colección Eloquent a la colección base

collapse, flatten, flip, keys, pluck y zip devuelven Illuminate\Support\Collection.
Además, si el resultado de map no contiene modelos Eloquent, también se convierte en la colección base.

​

Colecciones personalizadas

Si necesitas una clase de colección específica para un modelo, la opción más clara es usar el atributo #[CollectedBy].

​

Atributo #[CollectedBy] (recomendado)

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

​

Método 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;
    }
}

Al definir newCollection() o #[CollectedBy], la colección personalizada se devuelve donde normalmente se devolvería Eloquent\Collection.
Si quieres aplicarlo a todos los modelos, define newCollection() en un modelo base común.

​

Páginas relacionadas

Colecciones

Repasa primero las operaciones básicas de Illuminate\\Support\\Collection.

Introducción a Eloquent

Aclara los fundamentos de modelos y consultas antes de trabajar con colecciones Eloquent.