Laravel Eloquent Collections

Tempo de leitura: 5 minutos

Laravel Eloquent Collections: No desenvolvimento web com Laravel, lidar com conjuntos de dados é uma tarefa constante. Seja recuperando dados do banco de dados com o Eloquent ORM ou processando arrays, a manipulação eficiente desses dados é crucial para o desempenho e a manutenibilidade da aplicação. É aí que entram as eloquent collections, uma poderosa abstração que oferece uma interface fluente e expressiva para trabalhar com arrays de dados.

Este artigo explora em detalhes as eloquent collections no Laravel, desde os métodos disponíveis até a criação de coleções personalizadas, permitindo que você domine essa ferramenta essencial.

O que são Eloquent Collections?

Laravel Eloquent Collections: As eloquent collections são instâncias da classe Illuminate\Support\Collection. Elas fornecem um conjunto rico de métodos para iterar, filtrar, transformar e manipular arrays de dados de forma concisa e legível. A grande vantagem é que os resultados de consultas Eloquent (como User::all() ou User::where('active', 1)->get()) já retornam instâncias de Collection, permitindo o uso imediato desses métodos.

Métodos Disponíveis

A classe Laravel Collection oferece uma vasta gama de métodos para diversas operações. Abaixo, destacamos alguns dos mais utilizados, agrupados por funcionalidade:

Iteração e Transformação:

map(callable $callback): Aplica um callback a cada item da coleção e retorna uma nova coleção com os resultados.
each(callable $callback): Itera sobre os itens da coleção e executa um callback para cada um, sem modificar a coleção original.
filter(callable $callback): Filtra os itens da coleção com base em um callback, retornando uma nova coleção com os itens que passaram no teste.
reject(callable $callback): O inverso de filter(). Retorna uma nova coleção com os itens que não passaram no teste do callback.
reduce(callable $callback, $initial = null): Reduz a coleção a um único valor, aplicando um callback cumulativamente a cada item.
flatMap(callable $callback): Mapeia e depois “achata” a coleção em um único nível. Útil para lidar com coleções aninhadas.
pluck($value, $key = null): Retorna uma nova coleção com os valores de uma determinada chave. Opcionalmente, você pode especificar uma chave para indexar os resultados.

Filtragem e Busca:

where($key, $operator = null, $value = null): Filtra os itens com base em uma condição.
whereIn($key, $values): Filtra os itens onde o valor de uma chave está presente em um array de valores.
first(callable $callback = null, $default = null): Retorna o primeiro item da coleção. Opcionalmente, você pode passar um callback para filtrar o primeiro item correspondente.
last(callable $callback = null, $default = null): Semelhante ao first(), mas retorna o último item.
contains($key, $value = null) ou contains(mixed $value): Verifica se a coleção contém um determinado valor ou um par chave/valor.
find(callable $callback = null): Retorna o primeiro item que satisfaz o teste do callback.

Ordenação:

sortBy($callback, $options = SORT_REGULAR, $descending = false): Ordena a coleção pelos resultados de um callback.
sortByDesc($callback): Ordena a coleção em ordem decrescente pelos resultados de um callback.

Agregação:

count(): Retorna o número de itens na coleção.
sum($callback = null): Retorna a soma dos valores da coleção.
avg($callback = null): Retorna a média dos valores da coleção.
min($callback = null): Retorna o menor valor da coleção.
max($callback = null): Retorna o maior valor da coleção.

Outros Métodos Úteis:

toJson($options = 0): Converte a coleção para uma string JSON.
toArray(): Converte a coleção para um array PHP.
values(): Retorna uma nova coleção com as chaves reindexadas sequencialmente.
keys(): Retorna uma nova coleção com as chaves da coleção original.
merge(iterable $items): Mescla a coleção com outro array ou coleção.
diff(iterable $items): Retorna os itens presentes na coleção original que não estão presentes em outra coleção.
unique($key = null, $strict = false): Retorna os itens únicos da coleção.

Coleções Personalizadas

Além dos métodos fornecidos pela classe Collection, você pode criar suas próprias coleções personalizadas para adicionar funcionalidades específicas ao seu domínio. Isso é especialmente útil para encapsular lógica de negócios complexa e tornar seu código mais organizado e reutilizável.

Para criar uma coleção personalizada, crie uma nova classe que estenda Illuminate\Support\Collection:

PHP

<?php

namespace App\Support;

use Illuminate\Support\Collection;

class ProductCollection extends Collection
{
    public function totalValue()
    {
        return $this->sum(function ($product) {
            return $product->price * $product->quantity;
        });
    }

    public function withDiscount($discountPercentage) {
        return $this->map(function ($product) use ($discountPercentage) {
            $product->discounted_price = $product->price * (1 - ($discountPercentage/100));
            return $product;
        });
    }
}

Para usar sua coleção personalizada, você precisa sobrescrever o método newCollection() no seu model Eloquent:

PHP

<?php

namespace App\Models;

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

class Product extends Model
{
    public function newCollection(array $models = [])
    {
        return new ProductCollection($models);
    }
}

Agora, quando você recuperar instâncias do model Product, você receberá uma instância de ProductCollection, permitindo o uso dos métodos personalizados:

PHP

$products = Product::all(); // Retorna uma instância de ProductCollection

$total = $products->totalValue();
$productsWithDiscount = $products->withDiscount(10);

Exemplo Completo: Calculando o valor total de um carrinho de compras com Coleção Personalizada

Suponha que você tenha um model CartItem com atributos product_id e quantity. Você pode criar uma coleção personalizada para calcular o valor total do carrinho:

PHP

// app/Support/CartItemCollection.php
<?php

namespace App\Support;

use Illuminate\Support\Collection;

class CartItemCollection extends Collection
{
    public function totalPrice()
    {
        return $this->sum(function ($item) {
            return $item->product->price * $item->quantity;
        });
    }
}

// app/Models/CartItem.php
<?php

namespace App\Models;

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

class CartItem extends Model
{
    protected $with = ['product']; // Garante que o produto seja carregado

    public function product() {
        return $this->belongsTo(Product::class);
    }

    public function newCollection(array $models = [])
    {
        return new CartItemCollection($models);
    }
}

// Em um controller:
$cartItems = CartItem::all(); // Retorna CartItemCollection
$total = $cartItems->totalPrice();

return view('cart.show', ['cartItems' => $cartItems, 'total' => $total]);

Na view cart.show:

Blade

Total do Carrinho: R$ {{ $total }}

Conclusão

Laravel Eloquent Collections: As eloquent collections são uma ferramenta poderosa para manipular dados no Laravel, oferecendo uma sintaxe fluente e uma ampla gama de métodos. A capacidade de criar coleções personalizadas permite encapsular lógica específica do seu domínio, tornando o código mais limpo, organizado e reutilizável. Ao dominar as eloquent collections, você aprimorará significativamente sua produtividade e a qualidade do seu código Laravel.

Lembre-se de escolher o método mais adequado para cada situação e de aproveitar o poder das coleções personalizadas para resolver problemas complexos de forma elegante.

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: