O Eloquent é o ORM incluído no Laravel e representa cada tabela por uma classe PHP chamada model. Em vez de montar SQL em cada tela, você chama métodos do model para buscar, gravar e relacionar registros. O ORM traduz essas chamadas para consultas no banco configurado.
A convenção reduz o código de ligação. Um model Invoice usa a tabela invoices, a chave primária id e as colunas created_at e updated_at. Quando a tabela foge desse padrão, você declara o nome e a chave no próprio model.
Uma consulta e uma gravação
O exemplo abaixo busca as faturas de um cliente e grava um novo registro:
$faturas = Fatura::where('cliente_id', $clienteId) ->orderByDesc('criado_em') ->limit(20) ->get();
$fatura = Fatura::create([ 'cliente_id' => $clienteId, 'total' => 149.90,]);O primeiro trecho produz um select com where, order by e limit. O segundo produz um insert e devolve o model com a chave gerada. O método create preenche apenas os campos declarados em $fillable ou liberados por $guarded, o que limita campos enviados por um formulário.
A leitura do SQL gerado permite conferir o que o ORM montou. O método toSql() mostra a consulta, e o log de consultas do Laravel registra o que foi executado. Essa leitura é útil quando um índice não está sendo usado ou quando uma consulta retorna mais linhas que o esperado.
Relações e o problema N+1
As relações aparecem como métodos no model, e um cliente tem muitas faturas com hasMany, enquanto uma fatura pertence a um cliente com belongsTo, o que permite navegar entre os registros: $fatura->cliente->nome.
O acesso dentro de um laço cria o problema N+1. Você busca vinte faturas com uma consulta e, para cada fatura, o ORM consulta o cliente. São vinte e uma consultas. O carregamento eager resolve o caso:
$faturas = Fatura::with('cliente')->limit(20)->get();Com with, o Eloquent busca as faturas e depois os clientes relacionados numa segunda consulta. O total cai para duas. O efeito surge no log e no tempo de resposta, especialmente quando a lista cresce.
O que o model não resolve
O Eloquent não cria índices, não define o tipo das colunas e não substitui uma migration. A estrutura da tabela continua nos arquivos de migration, versionados no Git. Uma coluna sem índice pode deixar a consulta lenta mesmo quando o código do model está correto.
O ORM também não define permissão de acesso. Um Fatura::all() devolve todos os registros que a conexão do banco pode ler. A filtragem por usuário precisa estar na consulta, na policy ou na política de acesso. A credencial do banco não deve ser a única barreira entre uma sessão e os registros de outro usuário.
Quando usar o Query Builder
O Eloquent é conveniente para o CRUD e para as relações do domínio. Em relatórios com junções complexas, o Query Builder ou uma consulta SQL escrita à mão podem ser mais claros. Os dois caminhos usam a mesma conexão e podem conviver no projeto.
A escolha não muda o banco. Uma consulta do Query Builder continua sendo SQL enviado ao Postgres ou ao MySQL. O banco de dados segue as garantias de transação, isolamento e índice, independentemente da camada que montou a consulta.
Dúvidas frequentes
Perguntas frequentes sobre Eloquent
- O Eloquent substitui o conhecimento de SQL?
- Não. O ORM monta consultas a partir dos métodos, mas índices, junções e planos de execução continuam no banco. Uma consulta lenta no Eloquent precisa ser lida no SQL gerado e no plano do Postgres ou do MySQL.
- O que é o problema N+1?
- É a repetição de uma consulta por item de uma lista. Você carrega vinte faturas e, para cada um, o ORM consulta o cliente. O carregamento eager, com with(), busca os clientes numa consulta adicional e reduz o total.
- Preciso declarar todas as colunas no model?
- Não. O Eloquent segue convenções para tabela, chave primária e datas. Você declara o que foge do padrão, como o nome da tabela, a chave, os campos preenchíveis e as conversões de tipo.
Para continuar
Recursos relacionados
Documentação
Laravel: Eloquent ORM
Cobre models, consultas, gravação, mutators, casts e exclusão lógica com os exemplos da versão atual.
Abrir recursoDocumentação
Laravel: relações do Eloquent
Explica hasOne, hasMany, belongsTo, belongsToMany e o carregamento eager usado para evitar consultas repetidas.
Abrir recursoSite de referência
Promovaweb: o que é o Laravel
Situa o Eloquent no ciclo de uma requisição, ao lado de rotas, controllers, migrations e Blade.
Abrir recursoAplicação na formação
Vibe Coding: Do Zero ao MVP
Ao gerar uma aplicação com o Laravel, você lê o model, confere as relações e revisa as consultas para não esconder um problema de banco atrás do ORM.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.