Usando escopos do Eloquent para construir consultas mais limpas no Laravel \| TreinaWeb Promoção no ar Matricule-se agora e garanta **54% de desconto** Termina em Tempo restante da oferta: 00 Horas 56 Min 30 Seg Tempo restante da oferta: 00 56 30 [Assinar →](https://www.treinaweb.com.br/checkout/pagamento/plano/anual?cupom=TW-SCLIENTE26) [ ](https://www.treinaweb.com.br) Explorar [ Quanto custa? ](#assinatura) [ FAQ ](https://www.treinaweb.com.br#faq) [Matricule-se](#assinatura) [ Entrar ](https://www.treinaweb.com.br/login) [ Início ](https://www.treinaweb.com.br) [ Artigos ](https://www.treinaweb.com.br/blog) Usando escopos do Eloquent para construir consultas mais limpas no Laravel [ PHP ](https://www.treinaweb.com.br/blog/categoria/php) # Usando escopos do Eloquent para construir consultas mais limpas no Laravel Veja como é possível, a partir dos escopos, reutilizar pequenos trechos de código no Eloquent e deixar as consultas mais limpas e legíveis. [ Elton Fonseca ](https://www.treinaweb.com.br/blog/autor/elton-fonseca) 9 anos atrás ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2018/03/03163146/usando-escopos-do-eloquent.png) É comum precisarmos por diversas vezes fazer consultas que envolvam o mesmo trecho de código. Pensando nisso, o [Eloquent](https://www.treinaweb.com.br/blog/tag/eloquent/ "Eloquent") possui os escopos, que permitem aplicar modificadores nas consultas. Esses modificadores podem ser aplicados em dois níveis ao model: local e global. [ ![Laravel - Eloquent ORM](https://d2knvm16wkt3ia.cloudfront.net/assets/svg-icon/laravel.svg) Curso Laravel - Eloquent ORM Conhecer o curso ](https://www.treinaweb.com.br/curso/laravel-eloquent-orm) ## Escopo local O escopo local permite criar métodos com modificadores. Esses métodos podem ser aplicados a uma consulta como se fossem métodos próprios do Eloquent. Vamos supor que em um model chamado `Client` exista uma coluna `limit` que indica o limite de compra do cliente. É possível imaginar que diversas vezes no projeto precisaremos buscar clientes que possuam limite maior que `0`. Poderíamos ter como exemplo as seguintes consultas: **1) Buscar por nome dos clientes que possuem limite:** ```php Client::where('limit', '>', 0)->where('name', 'like', $nome)->get(); ``` **2) Buscar por cidade dos clients que possuem limite:** ```php Client::where('limit', '>', 0)->where('city', $cidade)->get(); ``` Note que repetimos o mesmo código `where('limit', '>', 0)` nas duas consultas. Isso pode não ser muito bom pois, caso a regra de negocio mude, será necessário alterar dentro de cada local do projeto. A criação de um escopo pode resolver o problema acima facilmente. Para criar um novo escopo basta definir um método publico na classe do model, ele deve ter o nome no padrão `scopeNomeEscopo` e receber um parâmetro que contém a instancia do `Builder`. Veja o exemplo de escopo para definir o `limite > 0`: ```php namespace App; use Illuminate\Database\Eloquent\Model; class Client extends Model { /* * Escopo que busca clientes com limite * * @param \Illuminate\Database\Eloquent\Builder $query * @return \Illuminate\Database\Eloquent\Builder */ public function scopeHasLimit($query) { return $query->where('limit', '>', 0); } } ``` Agora podemos usar o escopo facilmente na consulta como se fosse um método do próprio Eloquent: Busca por nome dos clientes que possuem limite: ```php Client::hasLimit()->where('name', 'like', $nome)->get(); ``` Busca por cidade dos clients que possuem limite: ```php Client::hasLimit()->where('city', $cidade)->get(); ``` À primeira vista, parece não ter muita diferença, mas já ganhamos na legibilidade da leitura das consultas, quantidade de código digitado e também na definição única do código. Vamos supor que agora ao invés de 0 o limite deve ser maior que 100 e que precise também sempre ordenar pelo maior limite. Provavelmente você ficaria muito feliz em precisar alterar em apenas um local ao invés de vários, além de ter que ficar olhando cada consulta para conferir se está tudo certo. ## Escopo global O escopo global é muito útil quando necessário aplicar um modificador a todos os registros que forem buscados no model. Ao invés de definirmos em cada consulta os modificadores, ou até mesmo criar escopos locais e aplicar em cada consulta, podemos declarar o escopo global. Vamos supor devemos mostrar apenas clientes ativos e que eles sejam ordenados pela data de cadastro. Podemos adicionar dois escopos: ```php namespace App; use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Builder; class Client extends Model { /** * The "booting" method of the model. * * @return void */ protected static function boot() { parent::boot(); //filtra apenas por clientes ativos static::addGlobalScope('active', function (Builder $builder) { $builder->where('active', true); }); //ordena pela data de cadastro static::addGlobalScope('created', function (Builder $builder) { $builder->orderBy('created_at'); }); } } ``` Agora, toda vez que consultar os clientes automaticamente esses dois modificadores são aplicados. ### Consulta sem utilizar o escopo global Caso não queira aplicar em uma consulta especifica basta chamar o método `withoutGlobalScopes()`: ```php Client::withoutGlobalScopes()->get(); ``` Se quiser deixar de aplicar apenas um escopo global especifico, basta passar o nome dele: ```php Client::withoutGlobalScope('created')->get(); ``` ## Escopo global usando classe própria É possível também passar uma classe ao invés de uma função anônima para o método `addGlobalScope()`: ```php static::addGlobalScope(new \App\Scopes\ActiveScope); ``` Nesse caso a classe para aplicar a condição de ativo ao cliente fica: ```php namespace App\Scopes; use Illuminate\Database\Eloquent\Scope; use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Builder; class ActiveScope implements Scope { /** * Apply the scope to a given Eloquent query builder. * * @param \Illuminate\Database\Eloquent\Builder $builder * @param \Illuminate\Database\Eloquent\Model $model * @return void */ public function apply(Builder $builder, Model $model) { $builder->where('active', true); } } ``` ## Conclusão O uso de escopo nos ajuda na legibilidade das nossas buscas e torna o código menos repetitivo. Se aplicado de maneira correta, ele pode ajudar bastante na qualidade do código e facilitar futuras manutenções. Já leu nossos artigos sobre Laravel e Eloquent? Veja [como aliviar seus controllers com os eventos do Eloquent no Laravel](https://www.treinaweb.com.br/blog/como-aliviar-seus-controllers-com-os-eventos-eloquent-no-laravel/ "como aliviar seus controllers com os eventos do Eloquent no Laravel") e como [remover a lógica das views com presenters no Laravel](https://www.treinaweb.com.br/blog/removendo-logica-das-views-com-presenters-no-laravel/ "remover a lógica das views com presenters no Laravel"), tudo aqui no blog da Treina Web. - [ #Laravel ](https://www.treinaweb.com.br/blog/tag/laravel) - [ #Eloquent ](https://www.treinaweb.com.br/blog/tag/eloquent) - [ #escopos ](https://www.treinaweb.com.br/blog/tag/escopos) - [ #filtros ](https://www.treinaweb.com.br/blog/tag/filtros) - [ #buscas ](https://www.treinaweb.com.br/blog/tag/buscas) Autor ![Elton Fonseca](//secure.gravatar.com/avatar/2cee05645357ced0841ce76ba5569c72?d=mm) ## Elton Fonseca Professor e desenvolvedor. Formado em análise e desenvolvimento de sistema, pós graduado em engenharia e arquitetura de software. É autor de cursos em diversos temas, como, desenvolvimento back-end, cloud computing e CMSs. Nas horas vagas adora estudar sobre o mercado financeiro, cozinhar e brincar com pequeno Daniel. [@eltonfonsecadev](https://twitter.com/eltonfonsecadev) [Todos os artigos](https://www.treinaweb.com.br/blog/autor/elton-fonseca) ## Continue estudando Transforme leitura em prática com os cursos e formações da TreinaWeb. [Ver cursos](https://www.treinaweb.com.br/cursos) Continue lendo ## Artigos relacionados - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2019/03/26181326/CAPA-ELTON-MARÇO-400x280.png) [ PHP ](https://www.treinaweb.com.br/blog/categoria/php) 8 anos atrás ## [ Como melhorar o retorno das suas APIs no Laravel com API Resource do Eloquent ](https://www.treinaweb.com.br/blog/como-melhorar-o-retorno-das-suas-apis-no-laravel-com-api-resource-do-eloquent) Um dos pontos mais importantes quando estamos trabalhando APIs é o retorno dos dados. Veja como melhorar suas APIs no Laravel usando o API Resouce do Eloquent. Ler artigo - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2018/07/18131538/laravel-route-model-bind-400x280.jpg) [ PHP ](https://www.treinaweb.com.br/blog/categoria/php) 8 anos atrás ## [ Como se usa e o que resolve o recurso de Route Model Binding do Laravel ](https://www.treinaweb.com.br/blog/como-se-usa-e-o-que-resolve-o-recurso-de-route-model-binding-do-laravel) Saiba o que é o Route Model Binding do Laravel, qual problema ele resolve e como utilizá-lo de forma automática com Implicit Binding e manual com Explicit Binding. Ler artigo - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2018/03/07100631/VIEWS-LOGICA-LARAVEL-400x280.png) [ PHP ](https://www.treinaweb.com.br/blog/categoria/php) 9 anos atrás ## [ Removendo a lógica das views com presenters no Laravel ](https://www.treinaweb.com.br/blog/removendo-logica-das-views-com-presenters-no-laravel) Um dos problemas mais clássicos de aplicações que utilizam MVC é a camada de view concentrar lógica ao invés de apenas aspectos relacionados à exibição. Veremos nesse artigo como isso pode ser contornado. Ler artigo - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2021/02/CONHECENDO-VÁRIAVEIS-CONSTANTES-JAVASCRIPT-400x280.png) [ Desenvolvimento Front-end ](https://www.treinaweb.com.br/blog/categoria/desenvolvimento-front-end) 6 anos atrás ## [ Conhecendo variáveis e constantes no JavaScript ](https://www.treinaweb.com.br/blog/conhecendo-variaveis-e-constantes-no-javascript) Neste artigo vamos aprender a declarar e a utilizar constantes e variáveis no JavaScript, entendendo quando definir var, let e const. Ler artigo - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2023/07/DICA-CODIGO-PHP-400x280.jpg) [ PHP ](https://www.treinaweb.com.br/blog/categoria/php) 3 anos atrás ## [ Dica de Código: Propriedades Somente Leitura no PHP ](https://www.treinaweb.com.br/blog/dica-de-codigo-propriedades-somente-leitura-no-php) Descubra como utilizar as propriedades somente leitura no PHP 8.1 para criar código mais seguro e confiável. Ler artigo - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2019/02/13190452/php-cloud-400x280.jpg) [ PHP ](https://www.treinaweb.com.br/blog/categoria/php) 7 anos atrás ## [ Aplicação Serverless desenvolvida em PHP usando AWS Lambda ](https://www.treinaweb.com.br/blog/aplicacao-serverless-desenvolvida-em-php-usando-aws-lambda) Veja como fazer o deploy de uma aplicação PHP Serverless no AWS Lambda usando o Bref. Ler artigo - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2019/05/01125223/react-php-imagem-400x280.png) [ PHP ](https://www.treinaweb.com.br/blog/categoria/php) 8 anos atrás ## [ Introdução à programação assíncrona em PHP usando o ReactPHP ](https://www.treinaweb.com.br/blog/introducao-a-programacao-assincrona-em-php-usando-o-reactphp) Uma introdução à programação assíncrona com PHP e uso básico dos componentes do ReactPHP. Ler artigo - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2020/01/03075049/Inteligência-Artificial-Selecionando-Cores-400x280.png) [ Machine Learning ](https://www.treinaweb.com.br/blog/categoria/machine-learning) 7 anos atrás ## [ Desenvolva uma Inteligência Artificial que reconhece cores diretamente no navegador com TensorFlow.js ](https://www.treinaweb.com.br/blog/desenvolva-uma-inteligencia-artificial-que-reconhece-cores-diretamente-no-navegador-com-tensorflow-js) Aprenda a trabalhar com Machine Learning diretamente no navegador usando o TensorFlow.js Ler artigo - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2017/06/utilizando-o-firebase-authentication-em-uma-aplicacao-android-400x280.png) [ Android ](https://www.treinaweb.com.br/blog/categoria/android) 10 anos atrás ## [ Utilizando o Firebase Authentication em uma aplicação Android ](https://www.treinaweb.com.br/blog/utilizando-o-firebase-authentication-em-uma-aplicacao-android) Veja como implementar o Firebase Authentication em uma aplicação Android, usando o Android Studio. Ler artigo - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2023/04/contexto-execucao-JS-400x280.png) [ Javascript ](https://www.treinaweb.com.br/blog/categoria/javascript) 4 anos atrás ## [ Contexto de execução JavaScript ](https://www.treinaweb.com.br/blog/contexto-de-execucao-javascript) Contexto de execução JavaScript é um conceito abstrato que contém informações sobre o ambiente no qual o código atual está sendo executado Ler artigo - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2020/02/10171338/AUP-400x280.png) [ Engenharia de Software ](https://www.treinaweb.com.br/blog/categoria/engenharia-de-software) 7 anos atrás ## [ Afinal, o que é AUP - Processo Unificado Ágil? ](https://www.treinaweb.com.br/blog/afinal-o-que-e-aup-processo-unificado-agil) Vamos abordar neste artigo mais uma metodologia: AUP. Ler artigo - ![](https://dkrn4sk0rn31v.cloudfront.net/uploads/2019/06/14170401/COMANDOS-SYMFONY-400x280.png) [ PHP ](https://www.treinaweb.com.br/blog/categoria/php) 8 anos atrás ## [ Principais comandos do Symfony CLI ](https://www.treinaweb.com.br/blog/principais-comandos-do-symfony-cli) Nesse artigo falaremos sobre o utilitário de linha de comando symfony. Veremos como realizar a criação de projetos, utilizar o servidor de desenvolvimento, executar comandos da aplicação e outros recursos. Ler artigo ## Um ano de acesso total para você viver de programação. Todos os cursos e formações da TreinaWeb numa única assinatura, com professores que atuam no mercado, suporte direto e certificados. Do primeiro `console.log` ao mercado de trabalho. - **1 ano** de acesso a **todos os cursos** - Cursos novos **toda semana** - Suporte **direto com professores** - Plano de carreira **personalizado** - **Certificados digitais** inclusos - **Aplicativos** para Android e iOS, com **acesso offline** **Garantia incondicional de satisfação** Teste por 7 dias e, se não fizer sentido para você, devolvemos seu dinheiro. ### Acesso completo a todos os cursos e dezenas de Formações. 12 meses Economize R$ 840,00 54% OFF de 12x R$ 129,00 por apenas 12x R$ 59,00 sem juros no cartão de crédito ou R$ 599,00 à vista Oferta termina em **00h 56min 30s** - Acesso imediato e ilimitado durante 1 ano. - Plano de carreira personalizado. - Suporte direto com professores. - E muito mais! [Matricule-se agora](https://www.treinaweb.com.br/checkout/pagamento/plano/anual?cupom=TW-SCLIENTE26) [ ](https://www.treinaweb.com.br) Escola online de programação, tecnologia e IA. - [ ](https://www.facebook.com/TreinaWeb/) - [ ](https://www.instagram.com/treinaweb/) - [ ](https://www.youtube.com/user/TreinaWeb) - [ ](https://twitter.com/treinaweb) - [ ](https://www.linkedin.com/company/treinaweb) - [ ](https://github.com/treinaweb) ## Inscreva-se em nossa newsletter Receba lançamentos, promoções e novidades. Seu nome Seu WhatsApp Seu melhor e-mail Inscrever-se ## Cursos - [ Base para Devs ](https://www.treinaweb.com.br/categoria/base-para-devs) - [ Front-end ](https://www.treinaweb.com.br/categoria/desenvolvimento-front-end) - [ Back-end ](https://www.treinaweb.com.br/categoria/desenvolvimento-back-end) - [ Mobile ](https://www.treinaweb.com.br/categoria/desenvolvimento-mobile) - [ Bancos de Dados ](https://www.treinaweb.com.br/categoria/bancos-de-dados) - [ Cloud ](https://www.treinaweb.com.br/categoria/cloud-computing) - [ IA ](https://www.treinaweb.com.br/categoria/ia) - [ E mais ](https://www.treinaweb.com.br/categoria/e-mais) - [ Ver todos os cursos ](https://www.treinaweb.com.br/cursos) ## Conteúdo - [ Formações ](https://www.treinaweb.com.br/formacoes) - [ Projetos práticos ](https://www.treinaweb.com.br/projetos-praticos) - [ Direto ao ponto ](https://www.treinaweb.com.br/direto-ao-ponto) - [ Planos ](https://www.treinaweb.com.br#assinatura) - [ Depoimentos ](https://www.treinaweb.com.br#depoimentos) - [ Comunidade ](https://www.treinaweb.com.br#comunidade) - [ Corpo docente ](https://www.treinaweb.com.br#docente) ## A empresa - [ Sobre a TreinaWeb ](https://www.treinaweb.com.br#sobre) - [ Perguntas frequentes ](https://www.treinaweb.com.br#faq) - [ Vantagens de estudar na TreinaWeb ](https://www.treinaweb.com.br/vantagens-de-estudar-na-treinaweb) - [ Cursos para empresas ](https://www.treinaweb.com.br/empresas) - [ Sugira um novo curso ](https://www.treinaweb.com.br/sugerir-curso) - [ Trabalhe conosco ](https://www.treinaweb.com.br/trabalhe-conosco) - [ Artigos ](https://www.treinaweb.com.br/blog) - [ Desenvolvedores e agentes ](https://www.treinaweb.com.br/developers) - [ Contato ](https://www.treinaweb.com.br/contato) - [ Política de privacidade ](https://www.treinaweb.com.br/politica-de-privacidade) - [ Termos de uso ](https://www.treinaweb.com.br/termos-de-uso) ## Baixe nosso aplicativo [ Disponível na **App Store** ](https://apps.apple.com/us/app/treinaweb/id1322729447) [ Disponível no **Google Play** ](https://play.google.com/store/apps/details?id=br.com.treinaweb.mobile) Av. Paulista, 1765, Conj 71 e 72 · Bela Vista · São Paulo · SP · 01311-200 © 2004 – 2026 TreinaWeb Tecnologia LTDA · CNPJ 06.156.637/0001-58