Laravel Scopes: O Guia Completo para Filtrar Consultas

Quando trabalhamos com aplicações robustas em Laravel, manter a lógica de consulta organizada, reutilizável e legível é essencial. É aí que entram os Eloquent Scopes — uma forma elegante de encapsular filtros de consultas no próprio modelo, evitando repetições e promovendo boas práticas de desenvolvimento.

Neste guia completo, você vai entender o que são os query scopes do Laravel, como criar local scopes e global scopes, e quando usá-los no seu projeto para deixar seu código limpo e eficiente.

O que são Eloquent Scopes?

No Laravel, Scopes são métodos que permitem adicionar restrições personalizadas às consultas do Eloquent. Eles funcionam como filtros reutilizáveis para os modelos, tornando o código mais limpo e expressivo.

Existem dois tipos principais de scopes:

• Local Scopes: escopos aplicáveis sob demanda.
• Global Scopes: escopos aplicados automaticamente em todas as consultas de um modelo.

Local Scopes: Reutilizando Filtros com Clareza

Um Local Scope é uma função que você define no seu modelo, e que pode ser utilizada em qualquer consulta para reaplicar uma lógica de filtro.

Criando um Local Scope

No modelo Eloquent, defina um método com prefixo scope seguido pelo nome do filtro (em StudlyCase). O nome usado na consulta será em camelCase:

// App\Models\Post.php

public function scopePublished($query)
{
    return $query->where('published', true);
}

Usando um Local Scope

Com o scope criado, você pode aplicá-lo diretamente nas consultas:

$posts = Post::published()->get();

É possível encadear com outras condições normalmente:

$posts = Post::published()->where('category', 'Laravel')->get();

Scopes com Parâmetros

Você também pode tornar o scope dinâmico, passando parâmetros:

public function scopeOfCategory($query, $category)
{
    return $query->where('category', $category);
}

// Uso:
Post::ofCategory('Laravel')->get();

Global Scopes: Aplicando Filtros por Padrão

Um Global Scope é aplicado automaticamente a todas as consultas de um modelo, a menos que seja explicitamente removido.

Criando um Global Scope

Crie uma classe que implemente a interface Scope:

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;

class PublishedScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        $builder->where('published', true);
    }
}

Aplicando o Scope no Modelo

Adicione o scope no método booted do modelo:

protected static function booted()
{
    static::addGlobalScope(new PublishedScope);
}

A partir de agora, todas as consultas a Post::all() ou Post::where(...) incluirão automaticamente where published = true.

Removendo um Global Scope

Você pode remover um scope global em uma consulta específica:

Post::withoutGlobalScope(PublishedScope::class)->get();

Quando Usar Scopes

• Use Local Scopes para filtros reutilizáveis que nem sempre precisam ser aplicados (ex: published, active, recent).
• Use Global Scopes quando uma restrição for padrão do modelo (ex: excluir registros “deletados” logicamente, usuários banidos, etc.).
• Scopes ajudam a manter os controladores e repositórios mais limpos e legíveis.

Vantagens de Usar Scopes

✅ Reutilização de Código: elimina duplicação de lógicas de filtragem.
✅ Legibilidade: consultas mais expressivas e fáceis de entender.
✅ Organização: centraliza a lógica de filtragem no modelo.
✅ Facilidade de manutenção: alterações em um único local se refletem em toda a aplicação.

Conclusão

Os Scopes do Laravel são uma ferramenta poderosa para manter seu código limpo, reutilizável e alinhado com as boas práticas do Eloquent. Seja usando local scopes para aplicar filtros específicos ou global scopes para comportamentos padrão, essa funcionalidade ajuda a transformar seu código em algo mais expressivo e profissional.

Dica final: sempre que perceber que está repetindo a mesma lógica de where, pense: isso poderia ser um scope?

🔥 Construa seus projetos com a melhor infraestrutura e ainda apoie o DevsBrasil!

Na Hostinger, você encontra hospedagem rápida, segura e com suporte top de linha — ideal para desenvolvedores e empreendedores digitais.

💡 Use o nosso link exclusivo do DevsBrasil e garanta:

✅ Descontos especiais nos planos de hospedagem, e-mail profissional, VPS e criador de sites com IA

✅ Ferramentas otimizadas para performance, com ótimo custo-benefício

✅ Apoio direto à nossa comunidade e ao nosso conteúdo gratuito 💚

👉 Acesse agora com nosso link exclusivo e aproveite os benefícios!