Laravel Query Builder

Tempo de leitura: 4 minutos

O Laravel Query Builder é uma interface elegante e poderosa que permite aos desenvolvedores construir e executar consultas SQL de forma programática, sem escrever SQL bruto. Ele atua como uma camada de abstração que simplifica o acesso ao banco de dados, oferece segurança contra injeções de SQL (graças ao uso automático de bindings) e melhora a legibilidade e manutenção do código.

Este artigo detalha as principais funcionalidades do Query Builder, desde filtros básicos até operações avançadas como Joins e Unions.

1. ⚙️ Estrutura e Recuperação Básica

Toda consulta começa com a Facade DB e o método table('nome_tabela'), que retorna uma instância do construtor de consultas.

A. Selecionando a Tabela

PHP

use Illuminate\Support\Facades\DB;

// Cria o construtor para a tabela 'users'
$query = DB::table('users'); 

// Executa a consulta SELECT * FROM users
$users = $query->get();

O método get() executa a consulta e retorna um objeto Collection contendo os resultados como objetos anônimos (stdClass).

B. Especificando Colunas (`select`)

Use select() para especificar as colunas que você deseja buscar, o que é crucial para performance.

PHP

// SELECT id, name, email FROM users
$users = DB::table('users')->select('id', 'name', 'email')->get();

Você também pode usar SQL Bruto com o método DB::raw() (com cautela):

PHP

// SELECT COUNT(*) as total_users FROM users
$users = DB::table('users')
            ->select(DB::raw('COUNT(*) as total_users'))
            ->get();

2. 🧩 Cláusulas de Filtro (`where`)

As cláusulas where são usadas para filtrar os resultados (equivalente à cláusula WHERE do SQL).

A. Filtros Simples e Comuns

Método	Equivalente SQL	Exemplo
`where`	`WHERE status = 'active'`	`where('status', 'active')`
`where`	`WHERE votes > 100`	`where('votes', '>', 100)`
`whereIn`	`WHERE id IN (1, 2, 3)`	`whereIn('id', [1, 2, 3])`
`whereBetween`	`WHERE votes BETWEEN 10 AND 100`	`whereBetween('votes', [10, 100])`

B. Cláusulas `OR` e Agrupamento

Para agrupar cláusulas WHERE de forma complexa (ex: WHERE A OR (B AND C)), você passa uma Closure para o método orWhere ou where.

PHP

$users = DB::table('users')
    ->where('status', 'active') // WHERE status = 'active'
    ->orWhere(function ($query) {
        $query->where('votes', '>', 100)  // AND (votes > 100
              ->where('country', 'US');   // AND country = 'US')
    })->get();

3. 🤝 Joins (Uniões)

O Query Builder suporta todos os tipos de Joins, permitindo que você combine dados de múltiplas tabelas.

A. Inner Join (Padrão)

Retorna apenas os registros onde há correspondência em ambas as tabelas.

PHP

// SELECT orders.*, users.name as user_name FROM orders 
// INNER JOIN users ON orders.user_id = users.id
$orders = DB::table('orders')
    ->join('users', 'orders.user_id', '=', 'users.id')
    ->select('orders.*', 'users.name as user_name')
    ->get();

B. Left Join

Retorna todos os registros da tabela da esquerda e os registros correspondentes da direita (NULL onde não houver correspondência).

PHP

$products = DB::table('products')
    ->leftJoin('categories', 'products.category_id', '=', 'categories.id')
    ->select('products.*', 'categories.name as category_name')
    ->get();

C. Unions

O método union() combina os resultados de duas consultas separadas (exigindo que as colunas selecionadas sejam as mesmas).

PHP

$activeUsers = DB::table('users')->where('status', 'active');
$usUsers = DB::table('users')->where('country', 'US');

// Combina os resultados, removendo duplicatas
$users = $activeUsers->union($usUsers)->get();

4. ✍️ Modificações de Dados (C.U.D)

A. Insert

O método insert() pode ser usado para inserir um ou múltiplos registros.

PHP

DB::table('users')->insert([
    'name' => 'John Doe',
    'email' => '[email protected]',
    'created_at' => now(), // Helpers de data/hora
    'updated_at' => now(),
]);

B. Update

O método update() é usado após uma ou mais cláusulas where.

PHP

DB::table('users')
    ->where('id', 1) // Filtro
    ->update(['votes' => 10, 'updated_at' => now()]); // Dados a atualizar

C. Delete e Truncate

O método delete() é usado para remover registros específicos, enquanto truncate() limpa a tabela inteira e reseta o auto-incremento.

PHP

// DELETE FROM users WHERE votes = 0
DB::table('users')->where('votes', 0)->delete(); 

// Exclui todos os registros e reseta o auto-incremento (rápido)
DB::table('logs')->truncate();

5. 📄 Paginação

O Query Builder suporta a paginação de resultados diretamente através do método paginate().

PHP

public function searchUsers(Request $request)
{
    $query = DB::table('users');

    // Aplica filtros dinâmicos
    if ($request->has('name')) {
        $query->where('name', 'like', '%' . $request->input('name') . '%');
    }

    // Retorna um Paginator com 10 resultados por página
    $users = $query->paginate(10); 

    return view('users.index', compact('users'));
}

✅ Conclusão Laravel Query Builder

Laravel Query Builder: É uma ferramenta essencial para construir queries de banco de dados de forma segura e expressiva. Embora o Eloquent ORM seja ideal para interações baseadas em objetos, o Query Builder oferece a flexibilidade e o controle de desempenho necessários para consultas diretas e complexas (como Joins e Unions), garantindo que seu código seja limpo, manutenível e protegido contra vulnerabilidades.

Mas antes de dominar o Laravel, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no Laravel, você precisará dominar as seguintes tecnologias: