mysqli_dump_debug_info

La fonction PHP mysqli_dump_debug_info() vide des informations de débogage de bas niveau sur une connexion MySQLi dans le journal des erreurs du serveur MySQL. Cette page explique ce que fait la fonction, dans quels cas elle est réellement utile, sa syntaxe en styles procédural et orienté objet, et comment interpréter la sortie qu'elle produit.

Ce que fait mysqli_dump_debug_info()

mysqli_dump_debug_info() demande à la bibliothèque cliente MySQL sous-jacente d'écrire des informations sur l'état interne de la connexion dans le fichier journal du serveur. Le type de détails qu'elle émet — tables ouvertes, objets en cache, utilisation mémoire de la connexion — est destiné aux développeurs de MySQL lui-même, et non au débogage courant d'une application. En pratique, vous y aurez recours uniquement lorsque vous tracerez un problème difficile à reproduire au niveau du pilote.

La fonction prend un seul argument, la connexion MySQLi, et retourne un boolean : true en cas de succès et false en cas d'échec. Elle ne retourne pas le texte de débogage à votre script ; les informations sont transmises directement au journal du serveur (l'emplacement dépend de votre configuration MySQL, souvent quelque chose comme /var/log/mysql/error.log).

Syntaxe

Il existe deux styles équivalents, car chaque fonctionnalité MySQLi est disponible à la fois comme fonction procédurale et comme méthode d'objet.

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

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

La valeur de retour est true si la demande de vidage des informations a réussi, et false dans le cas contraire.

Exemple procédural

L'exemple ci-dessous ouvre une connexion, demande un vidage de débogage et indique si la demande a réussi. Remplacez les identifiants par les vôtres pour l'exécuter sur un vrai serveur.

Vidage des informations de débogage (procédural)

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

Après l'exécution, ouvrez le journal des erreurs du serveur MySQL pour lire le vidage. La fonction elle-même indique uniquement si la demande a été acceptée — le texte de diagnostic réel se trouve dans le journal.

Exemple orienté objet

Si vous préférez l'API MySQLi orientée objet, appelez dump_debug_info() directement sur l'objet de connexion.

Vidage des informations de débogage (orienté objet)

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

Les deux styles font exactement la même chose ; choisissez celui qui correspond au reste de votre base de code.

Quand l'utiliser (et quand ne pas l'utiliser)

Recourez à mysqli_dump_debug_info() uniquement lorsque vous suspectez un problème au sein de la couche de connexion MySQL elle-même — par exemple, des requêtes préparées qui fuient ou une croissance mémoire inattendue sur une connexion de longue durée. Pour le débogage courant d'une application, vous voudrez presque toujours quelque chose de plus ciblé :

• Pour lire le message d'erreur du dernier appel MySQLi échoué, utilisez mysqli_error().
• Pour inspecter l'état et les statistiques d'une connexion, utilisez mysqli_get_connection_stats() ou consultez le statut de connexion.
• Pour une vue d'ensemble de l'extension, consultez le chapitre PHP MySQLi.

Remarque : la fonction n'écrit dans le journal du serveur que si le serveur MySQL a été compilé avec le support du débogage et est configuré pour l'accepter. Sur une version de production standard, elle peut silencieusement ne rien faire d'utile, ce qui est une raison de plus de la considérer comme un outil spécialisé plutôt que quotidien.

Conclusion

mysqli_dump_debug_info() est un outil de diagnostic étroit et de bas niveau qui vide les détails internes de la connexion MySQLi dans le journal du serveur MySQL et retourne un boolean indiquant si la demande a réussi. Il est précieux pour les investigations au niveau du pilote mais rarement le bon outil pour un usage quotidien — pour cela, préférez mysqli_error(), les statistiques de connexion ou la journalisation des erreurs propre à PHP.

Pratique