mysqli_dump_debug_info

A função PHP mysqli_dump_debug_info() despeja informações de depuração de baixo nível sobre uma conexão MySQLi no log de erros do servidor MySQL. Esta página explica o que a função faz, quando ela é realmente útil, sua sintaxe nos estilos procedural e orientado a objetos, e como interpretar a saída que ela produz.

O que mysqli_dump_debug_info() faz

mysqli_dump_debug_info() solicita que a biblioteca cliente MySQL subjacente grave informações de estado interno da conexão no arquivo de log do servidor. O tipo de detalhe que ela emite — tabelas abertas, objetos em cache, uso de memória da conexão — destina-se às pessoas que desenvolvem o próprio MySQL, e não para depuração cotidiana de aplicações. Na prática, você só recorrerá a ela quando estiver rastreando um problema difícil de reproduzir na camada do driver.

A função recebe um único argumento, a conexão MySQLi, e retorna um boolean: true em caso de sucesso e false em caso de falha. Ela não retorna o texto de depuração ao seu script; as informações vão diretamente para o log do servidor (o local depende da sua configuração MySQL, geralmente algo como /var/log/mysql/error.log).

Sintaxe

Existem dois estilos equivalentes, pois cada recurso do MySQLi está disponível tanto como função procedural quanto como método de objeto.

// Procedural style
mysqli_dump_debug_info(mysqli $mysql): bool

// Object-oriented style
$mysqli->dump_debug_info(): bool

O valor de retorno é true se a requisição para despejar as informações foi bem-sucedida, e false caso contrário.

Exemplo procedural

O exemplo abaixo abre uma conexão, solicita um despejo de depuração e informa se a requisição foi bem-sucedida. Substitua as credenciais pelas suas próprias para executá-lo em um servidor real.

Despejando informações de depuração (procedural)

<?php
// Throw exceptions instead of warnings on connection errors
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = mysqli_connect("localhost", "user", "password", "my_database");

// Ask the client library to write debug info to the MySQL server log
if (mysqli_dump_debug_info($mysqli)) {
    echo "Debug information was dumped to the server log.\n";
} else {
    echo "Could not dump debug information.\n";
}

mysqli_close($mysqli);
?>

Após executar isso, abra o log de erros do servidor MySQL para ler o despejo. A própria função apenas informa se a requisição foi aceita — o texto de diagnóstico real fica no log.

Exemplo orientado a objetos

Se você preferir a API MySQLi orientada a objetos, chame dump_debug_info() diretamente no object de conexão.

Despejando informações de depuração (orientado a objetos)

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = new mysqli("localhost", "user", "password", "my_database");

if ($mysqli->dump_debug_info()) {
    echo "Debug information was dumped to the server log.\n";
} else {
    echo "Could not dump debug information.\n";
}

$mysqli->close();
?>

Ambos os estilos fazem exatamente a mesma coisa; escolha o que melhor se encaixa no restante da sua base de código.

Quando usar (e quando não usar)

Recorra a mysqli_dump_debug_info() somente quando suspeitar de um problema dentro da própria camada de conexão MySQL — por exemplo, prepared statements com vazamento ou crescimento inesperado de memória em uma conexão de longa duração. Para depuração comum de aplicações, você quase sempre vai querer algo mais direcionado:

• Para ler a mensagem de erro da última chamada MySQLi com falha, use mysqli_error().
• Para inspecionar o estado e as estatísticas de uma conexão, use mysqli_get_connection_stats() ou verifique o status da conexão.
• Para uma visão geral mais ampla da extensão, consulte o capítulo PHP MySQLi.

Observação: a função só grava no log do servidor quando o servidor MySQL foi compilado com suporte a depuração e está configurado para aceitá-lo. Em uma versão de produção padrão, ela pode silenciosamente não fazer nada útil, o que é mais um motivo pelo qual ela é uma ferramenta especializada e não uma ferramenta do dia a dia.

Conclusão

mysqli_dump_debug_info() é um diagnóstico restrito e de baixo nível que despeja detalhes internos da conexão MySQLi no log do servidor MySQL e retorna um boolean indicando se a requisição foi bem-sucedida. É valioso para investigações no nível do driver, mas raramente é a ferramenta certa para o trabalho cotidiano — para isso, prefira mysqli_error(), estatísticas de conexão ou o próprio registro de erros do PHP.

Prática