Eloquent: Coleções

Introdução

Todos os múltiplos resultados retornados pelo Eloquent são uma instância do objeto Illuminate\Database\Eloquent\Collection, incluindo os resultados obtidos através do método get ou acessados por meio de um relacionamento. O objeto de coleção do Eloquent estende a collection básica do Laravel, por isso, naturalmente herda dezenas de métodos utilizados para trabalhar fluentemente com a arrays subjacentes de models Eloquent.

Claro que, todas as coleções (collections) também servem como iteradores, permitindo fazermos loop sobre elas como se fossem arrays PHP simples:

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

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

No entanto, as coleções são muito mais poderosas do que os arrays e expõe uma variedade de métodos para mapear/iterar pelos elementos da collection utilizando uma interface intuitiva. Por exemplo, vamos remover todos os models inativos e reunir o primeiro nome para cada usuário restante:

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

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

Métodos Disponíveis

A Coleção Básica

Todas as coleções Eloquent estendem a base do objeto Laravel collection portanto, elas herdam todos os métodos fortes fornecidos pela classe base de collection:

Coleções Personalizadas

Se você precisar usar um objeto Collection personalizado com seus próprios métodos de estensão, você pode sobrescrever o método newCollection em seu model:

<?php namespace App;

use App\CustomCollection;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Create a new Eloquent Collection instance.
     *
     * @param  array  $models
     * @return \Illuminate\Database\Eloquent\Collection
     */
    public function newCollection(array $models = [])
    {
        return new CustomCollection($models);
    }
}

Uma vez definido o método newCollection em seu model, você receberá uma instância da sua coleção personalizada do Eloquent que retornará sempre um objeto do tipo Collection. Se você necessita de uma coleção personalizada para cada model seu, você deverá substituir o método newCollection em uma classe model básica e estende-la em todos os seus models.