Query builder · PHP MVC Framework

Consulta encadeada

$result = (new User())
    ->select('id', 'name', 'email')
    ->where('active', 1)
    ->orderBy('name')
    ->paginate(15, 1);

O builder do Model inclui where, orWhere, whereIn, whereNotIn, whereNull, whereNotNull, whereBetween, whereLike, whereRaw, whereGroup, join, leftJoin, groupBy, having, orderBy, limit, offset e select.

Terminar consulta

get() retorna array; first() retorna objeto ou false; firstOrFail() retorna objeto ou falha; pluck(), value(), count(), exists() e paginate() atendem leituras específicas.

Segurança SQL

Use APIs de filtro que vinculam valores. whereRaw($sql,$bindings) permite expressão SQL e bindings; valores nunca devem ser concatenados na string SQL. Identificadores e operadores também passam por validação interna, mas isso não substitui query parametrizada.

Não há classe separada QueryBuilder: os métodos fluentes vivem em Model. Evite assumir joins relacionais automáticos, eager loading ou casts que não aparecem na implementação.

Básico · filtrar e encerrar a consulta

As chamadas fluentes acumulam condições no Model; um método terminal executa o SQL e retorna os dados. Valores de where são enviados em bindings PDO, enquanto nomes de colunas/operadores passam por validação do Model.

$page = (new \App\Models\User())
    ->select('id', 'name', 'email')
    ->where('active', 1)
    ->orderBy('name')
    ->paginate(15, 1);

`paginate($perPage,$page)` normaliza valores menores que 1, conta o total, limita a página ao intervalo disponível e devolve os dados com metadados. O `get()` retorna lista de objetos; `first()` retorna objeto ou false; `firstOrFail()` lança exceção quando não encontra.

Intermediário · agrupar OR para preservar precedência

Quando uma busca combina filtros obrigatórios com alternativas, agrupe o OR. Sem parênteses, um filtro de estado pode ser aplicado apenas a uma das alternativas.

$results = (new \App\Models\User())
    ->where('active', 1)
    ->whereGroup(function ($query): void {
        $query->whereLike('name', 'ana')
              ->whereLike('email', 'ana', 'or');
    })
    ->orderBy('name')
    ->get();

Esse exemplo demonstra whereGroup(), whereLike() com booleano OR e get(); orWhere() separado usa operador padrão =, não LIKE. Os métodos de builder alteram a instância; get()/paginate() executam e resetam o estado de consulta, então comece uma instância nova para outra consulta independente.

SQL dinâmico com cautela

Use `whereRaw($sql,$bindings)` somente quando o builder não expressar a condição. Bindings protegem valores, não identificadores: tabela, coluna, direção de ordenação e trechos de having devem ser constantes ou validados.

$results = (new \App\Models\User())
    ->whereRaw('created_at >= :inicio', ['inicio' => $inicio])
    ->get();

Não concatene input do usuário em SQL. updateWhere() e deleteWhere() recusam execução sem condições, mas ainda é sua responsabilidade verificar que o filtro representa o conjunto esperado.

Operadores, grupos e limites

Método	Contrato	Atenção
`where($column,$value,$op='=')`	Filtro AND; valor parametrizado.	Operador padrão é igualdade.
`orWhere($column,$value,$op='=')`	Filtro OR; valor parametrizado.	O padrão também é `=`; use `whereLike($column,$term,'or')` para OR + LIKE.
`whereLike($column,$value,$boolean='and')`	LIKE com binding; o Model adiciona curingas conforme a implementação.	Use argumento booleano and/or; não confunda com where() literal.
`whereRaw($sql,$bindings=[])`	Expressão SQL livre mais bindings para valores.	Bindings não sanitizam nomes de tabela/coluna nem SQL concatenado.
`whereGroup(callable $callback)`	Parênteses nas condições construídas dentro do callback.	Use para preservar precedência entre AND e OR.

Valores são parametrizados, mas colunas, joins, group/order by e trechos raw/having vêm de SQL/identificadores. Mantenha-os constantes ou valide-os com allowlist. orderBy() aceita direção validada pela implementação; direção inválida normaliza para ASC. Para paginação e reset, veja Models.

Conectores AND/OR são parâmetros de implementação, não entrada do usuário

Os filtros whereIn(string $column, array $values, string $boolean = 'and'): static, whereNotIn(...), whereNull(string $column, string $boolean = 'and'): static, whereNotNull(...), whereBetween(string $column, mixed $min, mixed $max, string $boolean = 'and'): static, whereLike(string $column, string $value, string $boolean = 'and'): static e whereGroup(callable $callback, string $boolean = 'and'): static armazenam o conector booleano fornecido. Use somente os literais 'and' e 'or' escolhidos no código.

A implementação atual não aplica allowlist a esses conectores em todos os métodos. Nunca derive $boolean de query string, body ou outro input HTTP. Bindings protegem valores, mas não autorizam fragmentos de sintaxe SQL.

$users->where('active', 1)
      ->whereLike('name', '%Ana%', 'or')
      ->get();