Laravel: Como visualizar a SQL com os valores preenchidos para facilitar o debug

Laravel: Como visualizar a SQL com os valores preenchidos para facilitar o debug
No dia a dia do desenvolvimento com Laravel, é comum precisarmos inspecionar uma query SQL gerada dinamicamente. A primeira ferramenta que muitos desenvolvedores usam é:
$query->toSql();

Porém, esse método não exibe os valores reais que serão enviados ao banco de dados. Em vez disso, mostra apenas a SQL com placeholders ?, o que pode dificultar o debug, principalmente em queries complexas.

Neste artigo, vou te mostrar como criar um helper simples para resolver isso, exibindo a SQL com os valores reais preenchidos, de forma segura e prática para uso em desenvolvimento.

O problema: SQL sem valores

Vamos supor que temos o seguinte código:
$query = DB::table('users')
    ->where('name', 'João')
    ->where('age', '>=', 30);

dd($query->toSql());
A saída será:
select * from users where name = ? and age >= ?
E os valores reais estão em:
$query->getBindings(); // ['João', 30]
Mas, e se quisermos ver a query completa com os valores aplicados?

Criando um helper debug_sql

Vamos montar um helper que junta os valores aos ? da query de forma segura e prática, ideal para debug. Arquivo: app/Helpers/debug_sql_helper.php
<?php

if (!function_exists('debug_sql')) {
    /**
     * Exibe a SQL com os bindings substituídos (somente para debug).
     *
     * @param \Illuminate\Database\Query\Builder|\Illuminate\Database\Eloquent\Builder $query
     * @param bool $return Se true, retorna a SQL em vez de dar dd().
     * @return string|void
     */
    function debug_sql($query, $return = false)
    {
        $sql = $query->toSql();
        $bindings = $query->getBindings();

        foreach ($bindings as $binding) {
            $binding = is_numeric($binding) ? $binding : "'" . addslashes($binding) . "'";
            $sql = preg_replace('/\?/', $binding, $sql, 1);
        }

        if ($return) {
            return $sql;
        }

        dd($sql);
    }
}

Ativando o helper no projeto

Para que o Laravel carregue esse helper automaticamente, adicione o caminho no composer.json:
"autoload": {
    "files": [
        "app/Helpers/debug_sql_helper.php"
    ]
}
E depois execute:
composer dump-autoload

Como usar o debug_sql

Agora você pode usar assim:
$query = DB::table('users')
    ->where('email', 'like', '%@example.com')
    ->where('status', 'active');

debug_sql($query); // Mostra a SQL com os valores reais
A saída será:
select * from users where email like '%@example.com' and status = 'active'
Você também pode obter a SQL como string, útil para logs ou testes:
$sql = debug_sql($query, true);
Log::info("SQL gerada: $sql");

Cuidados importantes

  • Não use esse helper em produção, pois ele apenas simula a substituição dos parâmetros e não oferece proteção contra SQL Injection. É uma ferramenta de desenvolvimento.

  • Esse método não executa a query, apenas exibe como ela seria enviada ao banco.

  • Não serve para queries com binding nomeado (:param), apenas as do tipo ?.

Ferramentas simples como essa podem economizar muito tempo de debug, principalmente quando estamos lidando com queries complexas, filtros dinâmicos e comportamento inesperado no banco de dados.

Se você trabalha com Laravel no dia a dia, recomendo adicionar esse helper no seu kit de ferramentas. E se quiser ir além, pode criar até um middleware para logar queries lentas com os valores já aplicados.

Comentários (0)

Nenhum comentário ainda. Seja o primeiro.

Continue lendo

Como rodar Laravel no WSL com Valet Linux (de verdade)

Como rodar Laravel no WSL com Valet Linux (de verdade)

Sim, dá pra desenvolver Laravel no Windows sem sofrer. Mas você precisa fazer do jeito certo: usando WSL + Valet Linux. Esqueça XAMPP, Laragon, Docker lento e até o WSL 1. O caminho mais fluido para trabalhar com…

Laravel, NGINX, php, Tutorial