Laravel Eloquent Collections

Tempo de leitura: 4 minutos

Laravel Eloquent Collections: No universo Laravel, a manipulação eficiente de conjuntos de dados é facilitada pelas Eloquent Collections. Uma Collection é uma instância da classe Illuminate\Support\Collection que envolve um array de dados, fornecendo uma interface fluente e rica em métodos para iterar, filtrar, transformar e agregar esses dados de forma legível e poderosa.

Toda consulta bem-sucedida do Eloquent (como User::all()) retorna uma Collection, permitindo o uso imediato de seus métodos.

1. 🎯 Métodos Essenciais para Manipulação de Collections

A força das Collections reside na sua vasta biblioteca de métodos, que eliminam a necessidade de loops manuais na maioria das vezes.

A. Iteração e Transformação

Método	Função	Exemplo
`map()`	Aplica um callback a cada item, retornando uma nova Collection.	`$nomes = $users->map(fn($u) => $u->name)->all();`
`each()`	Itera sobre a Collection para executar ações (efeito colateral).	`$users->each(fn($u) => $u->active = true);`
`pluck()`	Extrai os valores de uma chave específica, opcionalmente usando outra chave para indexar.	`$ids = $users->pluck('id');`
`flatMap()`	Mapeia e achata o resultado em uma única Collection (útil para coleções aninhadas).	`$tags = $posts->flatMap(fn($p) => $p->tags);`

B. Filtragem e Busca

Método	Função	Exemplo
`filter()`	Retorna itens que passam no teste do callback.	`$ativos = $users->filter(fn($u) => $u->status == 'active');`
`reject()`	Retorna itens que não passam no teste do callback.	`$inativos = $users->reject(fn($u) => $u->status == 'active');`
`where()`	Filtra a Collection pelo par chave/valor.	`$joao = $users->where('name', 'João');`
`contains()`	Verifica se a Collection contém um valor ou par chave/valor.	`$users->contains('email', '[email protected]');`
`first()` / `last()`	Retorna o primeiro ou último item que satisfaça a condição (ou o primeiro/último item).	`$primeiro = $users->first(fn($u) => $u->age > 30);`

C. Agregação e Ordenação

Método	Função	Exemplo
`sum()`	Soma os valores de uma chave ou dos resultados de um callback.	`$total = $items->sum('price');`
`count()`	Retorna o número de itens.	`$items->count();`
`avg()`	Calcula a média dos valores.	`$media = $grades->avg();`
`sortBy()` / `sortByDesc()`	Ordena a Collection com base em uma chave ou callback.	`$users->sortBy('name');`

2. 🧩 Coleções Personalizadas (Custom Collections)

Para encapsular lógica de negócios complexa e tornar o código mais reutilizável, você pode criar uma classe que estende Illuminate\Support\Collection.

A. Criando a Collection Personalizada

Defina novos métodos de domínio na sua nova classe.

PHP

// app/Support/ProductCollection.php
<?php

namespace App\Support;

use Illuminate\Support\Collection;

class ProductCollection extends Collection
{
    /**
     * Calcula o valor total do inventário (preço * quantidade)
     */
    public function totalInventoryValue(): float
    {
        return $this->sum(function ($product) {
            return $product->price * $product->stock;
        });
    }

    /**
     * Aplica um desconto a todos os produtos na coleção
     */
    public function applyDiscount(int $percentage): self
    {
        return $this->map(function ($product) use ($percentage) {
            $product->price = $product->price * (1 - ($percentage / 100));
            return $product;
        });
    }
}

B. Vinculando ao Eloquent Model

Para que o Eloquent retorne sua classe personalizada, sobrescreva o método newCollection() no seu Model.

PHP

// app/Models/Product.php
<?php

namespace App\Models;

use App\Support\ProductCollection;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    // ...

    /**
     * Sobrescreve o método para retornar a Collection personalizada
     */
    public function newCollection(array $models = []): ProductCollection
    {
        return new ProductCollection($models);
    }
}

C. Utilização

Agora, qualquer resultado de consulta do Product terá acesso aos seus métodos personalizados:

PHP

// Retorna uma instância de ProductCollection
$inventory = Product::where('active', 1)->get(); 

// Uso do método personalizado
$totalValue = $inventory->totalInventoryValue();

// Uso do método personalizado e encadeamento fluente
$productsWithDiscount = $inventory->applyDiscount(15)
                                  ->sortByDesc('price');

3. 🔄 Convertendo e Manipulando Tipos

Método	Função	Exemplo
`toArray()`	Converte a Collection (e seus Models internos) para um Array PHP aninhado.	`$array = $users->toArray();`
`toJson()`	Converte a Collection para uma string JSON.	`return $users->toJson();`
`values()`	Retorna uma nova Collection com as chaves reindexadas sequencialmente.	`$users->values();`
`keys()`	Retorna uma Collection contendo apenas as chaves da Collection original.	`$users->keys();`
`merge()`	Combina duas Collections ou arrays.	`$c1->merge($c2);`

✅ Conclusão Laravel Eloquent Collections

Laravel Eloquent Collections: As Eloquent Collections são a ferramenta fundamental para o processamento de dados pós-consulta no Laravel. Elas incentivam a escrita de código funcional, limpo e encadeável. Ao dominar os métodos nativos e, crucialmente, ao criar Coleções Personalizadas para encapsular a lógica de domínio, você garante maior reutilização e manutenibilidade no seu código, aprimorando significativamente a qualidade das suas aplicações Laravel.

Mas antes de dominar o Laravel, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no Laravel, você precisará dominar as seguintes tecnologias: