Eloquent: Colecciones

• Introducción
• Métodos disponibles
• Colecciones personalizadas

#Introducción

Todos los métodos de Eloquent que devuelven más de un resultado de modelo retornan instancias de la clase Illuminate\Database\Eloquent\Collection, incluyendo resultados obtenidos mediante el método get o accedidos a través de una relación. El objeto de colección Eloquent extiende la colección base de Laravel, por lo que hereda naturalmente docenas de métodos para trabajar de forma fluida con el array subyacente de modelos Eloquent. ¡Asegúrese de revisar la documentación de colecciones de Laravel para conocer todos estos métodos útiles!

Todas las colecciones también funcionan como iteradores, permitiéndole recorrerlas como si fueran arrays simples de PHP:

use App\Models\User;

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

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

Sin embargo, como se mencionó anteriormente, las colecciones son mucho más potentes que los arrays y exponen una variedad de operaciones map / reduce que pueden encadenarse usando una interfaz intuitiva. Por ejemplo, podemos eliminar todos los modelos inactivos y luego obtener el nombre de cada usuario restante:

$names = User::all()->reject(function (User $user) {
    return $user->active === false;
})->map(function (User $user) {
    return $user->name;
});

#Conversión de Colecciones Eloquent

Aunque la mayoría de los métodos de colección Eloquent devuelven una nueva instancia de una colección Eloquent, los métodos collapse, flatten, flip, keys, pluck y zip devuelven una instancia de la colección base. Asimismo, si una operación map devuelve una colección que no contiene modelos Eloquent, esta se convertirá en una instancia de colección base.

#Métodos disponibles

Todas las colecciones Eloquent extienden el objeto base de colección Laravel; por lo tanto, heredan todos los métodos potentes proporcionados por la clase base de colección.

Además, la clase Illuminate\Database\Eloquent\Collection proporciona un conjunto ampliado de métodos para ayudar a gestionar sus colecciones de modelos. La mayoría de los métodos devuelven instancias de Illuminate\Database\Eloquent\Collection; sin embargo, algunos métodos, como modelKeys, devuelven una instancia de Illuminate\Support\Collection.

#append($attributes) {.collection-method .first-collection-method}

El método append puede usarse para indicar que un atributo debe ser agregado a cada modelo en la colección. Este método acepta un array de atributos o un solo atributo:

$users->append('team');

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

#contains($key, $operator = null, $value = null) {.collection-method}

El método contains puede usarse para determinar si una instancia de modelo dada está contenida en la colección. Este método acepta una clave primaria o una instancia de modelo:

$users->contains(1);

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

#diff($items) {.collection-method}

El método diff devuelve todos los modelos que no están presentes en la colección dada:

use App\Models\User;

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

#except($keys) {.collection-method}

El método except devuelve todos los modelos que no tienen las claves primarias dadas:

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

#find($key) {.collection-method}

El método find devuelve el modelo que tiene una clave primaria que coincide con la clave dada. Si $key es una instancia de modelo, find intentará devolver un modelo que coincida con la clave primaria. Si $key es un array de claves, find devolverá todos los modelos que tengan una clave primaria en el array dado:

$users = User::all();

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

#fresh($with = []) {.collection-method}

El método fresh recupera una instancia fresca de cada modelo en la colección desde la base de datos. Además, cualquier relación especificada será cargada eager:

$users = $users->fresh();

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

#intersect($items) {.collection-method}

El método intersect devuelve todos los modelos que también están presentes en la colección dada:

use App\Models\User;

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

#load($relations) {.collection-method}

El método load carga eager las relaciones dadas para todos los modelos en la colección:

$users->load(['comments', 'posts']);

$users->load('comments.author');

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

#loadMissing($relations) {.collection-method}

El método loadMissing carga eager las relaciones dadas para todos los modelos en la colección si las relaciones aún no están cargadas:

$users->loadMissing(['comments', 'posts']);

$users->loadMissing('comments.author');

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

#modelKeys() {.collection-method}

El método modelKeys devuelve las claves primarias de todos los modelos en la colección:

$users->modelKeys();

// [1, 2, 3, 4, 5]

#makeVisible($attributes) {.collection-method}

El método makeVisible hace visibles atributos que normalmente están "ocultos" en cada modelo de la colección:

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

#makeHidden($attributes) {.collection-method}

El método makeHidden oculta atributos que normalmente están "visibles" en cada modelo de la colección:

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

#only($keys) {.collection-method}

El método only devuelve todos los modelos que tienen las claves primarias dadas:

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

#setVisible($attributes) {.collection-method}

El método setVisible sobrescribe temporalmente todos los atributos visibles en cada modelo de la colección:

$users = $users->setVisible(['id', 'name']);

#setHidden($attributes) {.collection-method}

El método setHidden sobrescribe temporalmente todos los atributos ocultos en cada modelo de la colección:

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

#toQuery() {.collection-method}

El método toQuery devuelve una instancia del constructor de consultas Eloquent que contiene una restricción whereIn sobre las claves primarias del modelo de la colección:

use App\Models\User;

$users = User::where('status', 'VIP')->get();

$users->toQuery()->update([
    'status' => 'Administrator',
]);

#unique($key = null, $strict = false) {.collection-method}

El método unique devuelve todos los modelos únicos en la colección. Cualquier modelo del mismo tipo con la misma clave primaria que otro modelo en la colección será eliminado:

$users = $users->unique();

#Colecciones personalizadas

Si desea usar un objeto Collection personalizado al interactuar con un modelo dado, puede definir un método newCollection en su modelo:

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * Crear una nueva instancia de colección Eloquent.
     *
     * @param  array<int, \Illuminate\Database\Eloquent\Model>  $models
     * @return \Illuminate\Database\Eloquent\Collection<int, \Illuminate\Database\Eloquent\Model>
     */
    public function newCollection(array $models = []): Collection
    {
        return new UserCollection($models);
    }
}

Una vez que haya definido un método newCollection, recibirá una instancia de su colección personalizada cada vez que Eloquent normalmente devolvería una instancia de Illuminate\Database\Eloquent\Collection. Si desea usar una colección personalizada para todos los modelos en su aplicación, debe definir el método newCollection en una clase base de modelo que sea extendida por todos los modelos de su aplicación.