Consultas ao Banco de Dados (Query Builder)

1. Operações Essenciais com Models

A forma recomendada e utilizada no padrão MVC da MUCRM é através dos Models.

Consulta Simples

Busca apenas um registro.

$user = customer::where("id", 1)
    ->first();

Buscando pela Chave Primária

$user = customer::find(1);

Listando Registros

Retorna uma Collection com vários resultados.

$users = customer::select("id", "name")
    ->limit(10)
    ->get();

Atualizando Dados

Utilizando uma condição:

customer::where("id", 1)->update([
    "name" => "Novo Nome"
]);

Ou diretamente pela chave primária:

customer::update([
    "name" => "Novo Nome"
], 1);

Removendo Dados

Utilizando uma condição:

customer::where("id", 1)
    ->destroy();

Ou diretamente pela chave primária:

customer::destroy(1);

2. Filtros e Modificadores

Depois de dominar o básico, é possível utilizar filtros para refinar as consultas.

Ordenando Resultados

$top = customer::order_by("created_at", "DESC")
    ->limit(5)
    ->get();

Contando Registros

$total = customer::where("status", 1)
    ->count();

where_in()

Busca registros onde o campo corresponde a vários valores.

$users = customer::where_in("role", [1, 2, 3])
    ->get();

where_raw()

Permite criar cláusulas WHERE mais avançadas utilizando SQL diretamente.

$users = DB::table("users")
    ->where_raw(
        "status = ? AND name LIKE ?",
        [1, "%Admin%"]
    )
    ->get();

Utilizando Placeholders

Sempre utilize ? para representar os valores e passe os parâmetros através do array de bindings.

$users = DB::table("users")
    ->where_raw(
        "role = ? AND created_at >= ?",
        [1, "2025-01-01"]
    )
    ->get();

Exemplo com Múltiplas Condições

$users = DB::table("users")
    ->where_raw(
        "(status = ? OR role = ?) AND level >= ?",
        [1, 2, 100]
    )
    ->get();

Quando Utilizar

Utilize where_raw() apenas quando os métodos tradicionais não forem suficientes.

Em muitos casos, isto:

$users = customer::where("status", 1)
    ->where("role", 2)
    ->get();

é mais simples e legível do que:

$users = customer::where_raw(
    "status = ? AND role = ?",
    [1, 2]
)->get();

3. Joins e Agrupamentos

Permite consultar dados de múltiplas tabelas.

Join (Inner Join)

$data = customer::select("users.name", "profiles.avatar")
    ->join("profiles", "users.id", "=", "profiles.user_id")
    ->get();

Left Join

$data = customer::select("users.name", "profiles.avatar")
    ->left_join("profiles", "users.id", "=", "profiles.user_id")
    ->get();

group_by()

Agrupa registros repetidos.

$data = customer::select("role")
    ->group_by("role")
    ->get();

4. Utilizando DB::table()

Quando não existe um Model específico ou quando a consulta é mais direta, utilize a facade DB. Toda consulta começa informando a tabela:

DB::table("nome_da_tabela")

Exemplo Básico

use MUCRM\engine\support\facades\db;

$data = DB::table("users")
    ->order_by("created_at", "DESC")
    ->limit(5)
    ->get();

Consulta com Where

$user = DB::table("users")
    ->where("id", 1)
    ->get()
    ->first();

Consulta com Join

$data = DB::table("users")
    ->join("profiles", "users.id", "=", "profiles.user_id")
    ->get();

Definindo a Chave Primária

Como DB::table() não possui um Model associado, é possível definir a chave primária manualmente:

$item = DB::table("users")
    ->setPrimaryKey("id")
    ->where("id", 1)
    ->get()
    ->first();

5. PDO Puro

Para consultas extremamente específicas é possível utilizar PDO diretamente.

$stmt = DB::prepare(
    "SELECT name FROM users WHERE id = ?"
);

$stmt->execute([1]);

$result = $stmt->fetch();

6. Referência Rápida

select()    where()     where_in()   where_raw()
join()      left_join()  order_by()   group_by()
limit()     get()       first()     find()
count()     insert()    update()    destroy()

DB::table("users")
    ->limit(1)
    ->get()
    ->first();

Observações Importantes

• Models utilizam $table e $primaryKey
• Models são a forma recomendada de acesso ao banco
• DB::table() inicia um Query Builder manual
• setPrimaryKey() permite definir a chave primária manualmente
• get() retorna uma Collection
• first() retorna um único registro
• find($id) busca pela chave primária
• update() e destroy() possuem proteção contra execução sem where

Boas Práticas