Digite para filtrar os verbetes do Glossário.

    Desenvolvimento web · Vibe Coding: Do Zero ao MVP

    O que é Eloquent?

    O Eloquent é o ORM do Laravel. Cada model representa uma tabela e oferece métodos para consultar, gravar e relacionar registros sem SQL escrito à mão.

    Também chamado de: Eloquent ORM, ORM do Laravel

    StayCloudVPS Agêntica

    O mesmo ambiente do SetupVibe, agora numa VPS

    Os atalhos, o shell e as CLIs de IA que você já usa no computador rodam numa VPS da StayCloud com servidor no Brasil.

    Criar minha VPS na StayCloud

    Link de parceiro da Promovaweb.

    Black Friday até 30/11

    30%off

    nos 2 primeiros meses do plano mensal da VPS

    • Backup diário grátis para sempre
    • Servidores em São Paulo no datacenter da Ascenty
    • Datacenter Tier III manutenção sem parada
    • Acesso root com disco SSD NVMe
    • Réplica do backup em Ashburn, nos EUA

    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

    Aplicaçã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
    Capa da Formação Vibe Coding do Zero ao MVP

    Fontes consultadas

    Referências deste verbete

    Este verbete ajudou você?

    Planos Promovaweb

    Tire seus projetos do papel

    O Plano Martech cobre automação e atendimento. O Plano IA Makers acrescenta desenvolvimento com IA, enquanto o Plano Founders trata de gestão de negócios. Todos são anuais.

    Plano Martech

    Para conectar automação, marketing e atendimento com infraestrutura própria.

    R$ 897

    R$ 597/ano

    • Grade de automação, atendimento, marketing e análise de indicadores
    • Instalador Exclusivo Promovaweb
    • n8n, Evolution API, Chatwoot e Mautic
    • Trilha DevOps incluída
    • Encontros ao vivo (terça e quinta)
    • Comunidade e acompanhamento
    Conhecer o plano

    Plano Founders

    Plano anual para fazer um projeto de tecnologia avançar, com 90 dias de mentoria intensiva. R$ 1.997 à vista ou até 10x de R$ 219 no cartão.

    R$ 1.997/ano

    • 12 meses de acesso ao Founders
    • 90 dias de mentoria intensiva, um encontro por dia útil
    • Dia de conteúdo (terça e quinta) e War Room (segunda, quarta e sexta)
    • Encontro semanal em grupo após a fase intensiva
    • Formação Vibe Coding incluída no plano anual
    • Consultoria individual de até duas horas (bônus)
    Conhecer o plano