Posted on: December 22, 2025 03:39 PM
Posted by: Renato
Views: 154
Global Scope no Laravel: o que é, para que serve e quando usar
Quem trabalha com Laravel e Eloquent inevitavelmente se depara com filtros que se repetem o tempo todo:
“somente registros ativos”, “dados do usuário logado”, “registros do armazém atual”, “ignorar dados excluídos”.
Para resolver esse tipo de problema de forma centralizada, segura e elegante, o Laravel oferece o Global Scope.
Neste artigo, vamos entender o que é, para que serve, como criar, quando usar e quando evitar Global Scopes.
O que é Global Scope no Laravel?
Um Global Scope é um filtro que o Laravel aplica automaticamente em todas as consultas Eloquent de um model, sem que você precise chamá-lo explicitamente.
Ou seja, sempre que você fizer:
Model::query();
Model::all();
Model::where(...);
O filtro do Global Scope já estará embutido na query.
O exemplo mais famoso de Global Scope no Laravel é o Soft Delete, que automaticamente adiciona:
WHERE deleted_at IS NULL
em todas as consultas do model.
Para que serve um Global Scope?
Global Scopes servem para garantir regras de negócio que nunca devem ser esquecidas.
Eles são ideais quando:
-
A regra sempre deve ser aplicada
-
Esquecer o filtro pode causar erro grave ou vazamento de dados
-
O sistema precisa de consistência entre todas as queries
Exemplos clássicos de uso
-
✅ Filtrar apenas registros ativos (is_active = true)
-
🏢 Isolamento de dados em aplicações multi-tenant
-
👤 Dados pertencentes ao usuário logado
-
📦 Filtrar registros por empresa, filial ou armazém
-
🔒 Garantir que dados sensíveis nunca apareçam fora do contexto correto
Como criar um Global Scope
Existem duas formas principais:
inline no model ou usando uma classe dedicada (forma recomendada).
Criando um Global Scope com classe dedicada
1️⃣ Criar o Scope
Você pode criar manualmente ou usar o Artisan:
php artisan make:scope ActiveScope
// App/Scopes/ActiveScope.php
namespace App\Scopes;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;
class ActiveScope implements Scope
{
public function apply(Builder $builder, Model $model)
{
$builder->where('is_active', true);
}
}
2️⃣ Registrar o Scope no Model
// App/Models/Post.php
namespace App\Models;
use App\Scopes\ActiveScope;
use Illuminate\Database\Eloquent\Model;
class Post extends Model
{
protected static function booted()
{
static::addGlobalScope(new ActiveScope);
}
}
3️⃣ Usar normalmente
Nenhuma mudança é necessária nas consultas:
Post::all();
Post::where('category_id', 1)->get();
Todas já retornarão apenas registros com is_active = true.
Ignorando um Global Scope
Em relatórios, rotinas administrativas ou jobs, você pode precisar ignorar o filtro global.
Ignorar um scope específico
Post::withoutGlobalScope(ActiveScope::class)->get();
Ignorar todos os scopes
Post::withoutGlobalScopes()->get();
Isso é essencial para evitar “gambiarras” ou duplicação de models apenas para relatórios.
Global Scope inline (forma simples)
Para casos simples, também é possível definir o Global Scope direto no model:
class Post extends Model
{
protected static function booted()
{
static::addGlobalScope('active', function ($query) {
$query->where('is_active', true);
});
}
}
Apesar de funcionar bem, não é a melhor opção para regras reutilizáveis.
Global Scope vs Local Scope
É importante não confundir:
Local Scope (opcional)
public function scopeActive($query)
{
return $query->where('is_active', true);
}
Uso:
Post::active()->get();
Global Scope (obrigatório)
Aplicado automaticamente, sem chamada explícita.
Quando usar Global Scope?
Use Global Scope quando:
✅ A regra nunca deve ser esquecida
✅ Existe risco de vazamento de dados
✅ O sistema é multi-tenant
✅ O filtro faz parte do contexto obrigatório do model
Se esquecer esse filtro causa problema sério, ele deveria ser global.
Quando evitar Global Scope?
Evite quando:
⚠️ A regra é apenas conveniência
⚠️ O filtro muda muito conforme o contexto
⚠️ Pode confundir consultas complexas ou relatórios
⚠️ Depende de dados frágeis (ex: auth() sem verificação)
Nem todo where merece ser global.
Boas práticas
-
Prefira Scopes em classes dedicadas
-
Sempre documente scopes globais no model
-
Teste queries com e sem scopes
-
Use withoutGlobalScope() conscientemente
-
Evite lógica complexa dentro do apply()
Conclusão
O Global Scope é uma ferramenta poderosa do Laravel para centralizar regras de negócio, garantir segurança e reduzir repetição de código.
Quando bem utilizado, ele:
-
deixa o código mais limpo
-
reduz bugs silenciosos
-
protege dados sensíveis
-
facilita manutenção a longo prazo
Mas, como toda ferramenta poderosa, deve ser usada com critério e intenção clara.
Donate to Site
Renato
Developer