mysqli_dump_debug_info

La funzione PHP mysqli_dump_debug_info() scrive informazioni di debug di basso livello relative a una connessione MySQLi nel log degli errori del server MySQL. Questa pagina spiega cosa fa la funzione, quando è effettivamente utile, la sua sintassi in stile procedurale e orientato agli oggetti, e come leggere l'output che produce.

Cosa fa mysqli_dump_debug_info()

mysqli_dump_debug_info() chiede alla libreria client MySQL sottostante di scrivere informazioni sullo stato interno della connessione nel file di log del server. Il tipo di dettagli che emette — tabelle aperte, object in cache, utilizzo della memoria della connessione — è pensato per chi sviluppa MySQL stesso, non per il debug quotidiano delle applicazioni. In pratica la utilizzerai solo quando stai cercando di riprodurre un problema difficile da individuare a livello di driver.

La funzione accetta un singolo argomento, la connessione MySQLi, e restituisce un boolean: true in caso di successo e false in caso di errore. Non restituisce il testo di debug allo script; le informazioni vengono scritte direttamente nel log del server (la posizione dipende dalla configurazione MySQL, spesso qualcosa come /var/log/mysql/error.log).

Sintassi

Esistono due stili equivalenti, poiché ogni funzionalità MySQLi è disponibile sia come funzione procedurale sia come metodo object.

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

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

Il valore di ritorno è true se la richiesta di dump delle informazioni è andata a buon fine, false altrimenti.

Esempio procedurale

L'esempio seguente apre una connessione, richiede un dump di debug e segnala se la richiesta è riuscita. Sostituisci le credenziali con le tue per eseguirlo su un server reale.

Dump delle info di debug (procedurale)

<?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);
?>

Dopo aver eseguito questo codice, apri il log degli errori del server MySQL per leggere il dump. La funzione stessa indica solo se la richiesta è stata accettata — il testo diagnostico effettivo si trova nel log.

Esempio orientato agli oggetti

Se preferisci l'API MySQLi orientata agli oggetti, chiama dump_debug_info() direttamente sull'object di connessione.

Dump delle info di debug (orientato agli oggetti)

<?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();
?>

Entrambi gli stili fanno esattamente la stessa cosa; scegli quello che si adatta meglio al resto del tuo codebase.

Quando usarla (e quando no)

Ricorri a mysqli_dump_debug_info() solo quando sospetti un problema all'interno del layer di connessione MySQL stesso — ad esempio, prepared statement non rilasciati o una crescita inattesa della memoria su una connessione di lunga durata. Per il debug ordinario delle applicazioni vorrai quasi sempre qualcosa di più mirato:

• Per leggere il messaggio di errore dell'ultima chiamata MySQLi fallita, usa mysqli_error().
• Per ispezionare lo stato e le statistiche di una connessione, usa mysqli_get_connection_stats() o consulta lo stato della connessione.
• Per una panoramica più ampia dell'estensione, vedi il capitolo PHP MySQLi.

Nota: la funzione scrive nel log del server solo quando il server MySQL è stato compilato con il supporto al debug ed è configurato per accettarlo. Su una build di produzione standard potrebbe non fare nulla di utile in silenzio, il che è un ulteriore motivo per cui si tratta di uno strumento specialistico e non quotidiano.

Conclusione

mysqli_dump_debug_info() è uno strumento diagnostico ristretto e di basso livello che scrive i dettagli interni della connessione MySQLi nel log del server MySQL e restituisce un boolean che indica se la richiesta è andata a buon fine. È utile per indagini a livello di driver, ma raramente è lo strumento giusto per il lavoro quotidiano — in quei casi preferisci mysqli_error(), le statistiche di connessione o il sistema di error logging di PHP.

Esercitazione