logo oujood
🔍

mysqli_error() en PHP : Guide Complet pour Gérer les Erreurs de Requêtes MySQL

Apprenez à utiliser mysqli_error() pour identifier, capturer et journaliser les erreurs MySQL dans vos applications PHP avec des exemples pratiques et commentés.

OUJOOD.COM

La fonction mysqli_error() en PHP

PHP Version : 5+ (recommandé PHP 8.1+ en 2026)

La fonction mysqli_error() est une fonction intégrée de l'extension MySQLi (MySQL Improved) qui permet de récupérer le message descriptif de la dernière erreur MySQL survenue sur une connexion active. Elle est indispensable pour le débogage des requêtes SQL en PHP et la mise en place d'une gestion robuste des erreurs de base de données. En 2026, elle reste un outil fondamental, même si son usage s'inscrit désormais dans une stratégie globale incluant les exceptions PDO et la journalisation.

Syntaxes

La fonction mysqli_error() s'utilise selon deux paradigmes : orienté objet (OOP) et procédural. L'approche orientée objet est privilégiée dans les projets modernes PHP pour sa lisibilité et sa compatibilité avec les frameworks.

Syntaxe orientée objet

  📋 Copier le code

<?php
// Création de l'objet de connexion MySQLi
$mysqli = new mysqli("localhost", "utilisateur", "motdepasse", "ma_base");
// Vérification de la connexion
if ($mysqli->connect_error) {
    die("Erreur de connexion : " . $mysqli->connect_error);
}
// Après exécution d'une requête :
if (!$resultat) {
    echo "Erreur MySQL : " . $mysqli->error;
    // $mysqli->errno contient le code numérique de l'erreur
}

Syntaxe procédurale

  📋 Copier le code

<?php
// Connexion via la fonction procédurale mysqli_connect()
$conn = mysqli_connect("localhost", "utilisateur", "motdepasse", "ma_base");
// Vérification de la connexion avec mysqli_connect_error()
if (!$conn) {
    die("Erreur de connexion : " . mysqli_connect_error());
}
// Après une requête échouée, récupération du message d'erreur :
if (!$resultat) {
    echo "Erreur MySQL : " . mysqli_error($conn);
    // mysqli_errno($conn) retourne le code d'erreur numérique
}

Paramètres et valeurs de retour

En syntaxe procédurale, mysqli_error() accepte un seul paramètre obligatoire : $connection, l'objet ou le lien de connexion MySQLi actif. La fonction retourne une chaîne de caractères contenant le message d'erreur MySQL. Si aucune erreur n'est survenue, elle retourne une chaîne vide. Pour obtenir le code d'erreur numérique, utilisez mysqli_errno() en complément.

Exemples pratiques commentés

Exemple 1 — Approche orientée objet avec gestion d'erreur complète

Cet exemple illustre comment capturer une erreur SQL en PHP orienté objet et la journaliser de façon sécurisée sans exposer les détails sensibles à l'utilisateur final, conformément aux bonnes pratiques de sécurité 2026.

  📋 Copier le code

<?php
// Connexion à la base de données en OOP
$mysqli = new mysqli("localhost", "utilisateur", "motdepasse", "ma_base");
// Vérification immédiate de la connexion
if ($mysqli->connect_error) {
    // En production, journaliser l'erreur sans l'afficher
    error_log("Connexion échouée [" . $mysqli->connect_errno . "] : " . $mysqli->connect_error);
    die("Service temporairement indisponible.");
}
// Définition de la requête SQL — table inexistante pour forcer une erreur
$requete = "SELECT * FROM table_inexistante";
// Exécution de la requête via la méthode query()
$resultat = $mysqli->query($requete);
if (!$resultat) {
    // Récupération du code et du message d'erreur MySQLi
    $code  = $mysqli->errno;  // ex : 1146
    $msg   = $mysqli->error;  // ex : Table 'ma_base.table_inexistante' doesn't exist
    // Journalisation dans le fichier d'erreurs PHP
    error_log("Erreur SQL [$code] : $msg");
    // Message générique pour l'utilisateur
    echo "Une erreur est survenue. Veuillez réessayer.";
} else {
    // Traitement des lignes retournées
    while ($ligne = $resultat->fetch_assoc()) {
        echo htmlspecialchars($ligne['nom']);
    }
    // Libération mémoire
    $resultat->free();
}
// Fermeture de la connexion
$mysqli->close();

Exemple 2 — Approche procédurale avec mysqli_error()

L'approche procédurale reste couramment utilisée dans les scripts legacy et les environnements d'hébergement mutualisé. Voici comment gérer les erreurs mysqli en style procédural de manière structurée.

  📋 Copier le code

<?php
// Connexion procédurale à MySQL via mysqli_connect()
$conn = mysqli_connect("localhost", "utilisateur", "motdepasse", "ma_base");
if (!$conn) {
    // mysqli_connect_error() est spécifique aux erreurs de connexion
    error_log("Connexion impossible : " . mysqli_connect_error());
    die("Service indisponible.");
}
// Requête avec une colonne inexistante pour générer une erreur MySQL
$requete = "SELECT colonne_inexistante FROM utilisateurs";
$resultat = mysqli_query($conn, $requete);
if (!$resultat) {
    // Récupération du message d'erreur associé à la connexion $conn
    $code = mysqli_errno($conn); // Code numérique MySQL (ex : 1054)
    $msg  = mysqli_error($conn); // Description textuelle de l'erreur
    error_log("Erreur requête SQL [$code] : $msg");
    echo "Erreur lors de la récupération des données.";
} else {
    while ($ligne = mysqli_fetch_assoc($resultat)) {
        echo htmlspecialchars($ligne['nom']);
    }
    mysqli_free_result($resultat);
}
// Fermeture de la connexion
mysqli_close($conn);

Exemple 3 — Utilisation avec les requêtes préparées (recommandé en 2026)

En 2026, l'utilisation des requêtes préparées avec MySQLi est la norme pour prévenir les injections SQL. Voici comment capturer les erreurs sur un prepared statement avec mysqli_error().

  📋 Copier le code

<?php
$mysqli = new mysqli("localhost", "utilisateur", "motdepasse", "ma_base");
if ($mysqli->connect_error) {
    die("Connexion échouée : " . $mysqli->connect_error);
}
// Activation du mode exception pour MySQLi (PHP 8.1+)
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
try {
    // Préparation d'une requête paramétrée — évite les injections SQL
    $stmt = $mysqli->prepare("SELECT id, nom FROM utilisateurs WHERE email = ?");
    if (!$stmt) {
        // Erreur à la préparation : syntaxe invalide ou table inconnue
        throw new RuntimeException("Erreur préparation : " . $mysqli->error);
    }
    // Liaison du paramètre : 's' = string
    $email = "test@exemple.com";
    $stmt->bind_param("s", $email);
    // Exécution du statement préparé
    $stmt->execute();
    // Récupération du résultat
    $res = $stmt->get_result();
    while ($row = $res->fetch_assoc()) {
        echo htmlspecialchars($row['nom']) . "<br>";
    }
    $stmt->close();
} catch (mysqli_sql_exception $e) {
    // Capture les erreurs MySQLi lancées automatiquement avec MYSQLI_REPORT_STRICT
    error_log("Exception MySQLi : " . $e->getMessage());
    echo "Une erreur de base de données est survenue.";
} finally {
    $mysqli->close();
}

Bonnes pratiques et conseils d'utilisation en 2026

Pour une gestion professionnelle des erreurs MySQLi en PHP, voici les règles essentielles à appliquer dans tout projet :

  • Ne jamais afficher les messages d'erreur bruts en production : utilisez error_log() pour journaliser et affichez un message générique à l'utilisateur.
  • Activer le mode rapport d'erreurs MySQLi avec mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT) pour transformer les erreurs en exceptions attrapables avec try/catch.
  • Privilegier les requêtes préparées (prepare() + bind_param()) pour éliminer les risques d'injection SQL tout en conservant une gestion d'erreur précise.
  • Combiner mysqli_errno() et mysqli_error() pour obtenir à la fois le code numérique et la description textuelle de l'erreur, facilitant le diagnostic.
  • Envisager PDO comme alternative : PDO offre une interface unifiée multi-SGBD avec gestion native des exceptions, adaptée aux projets d'envergure.

En maîtrisant mysqli_error() et les mécanismes de gestion d'erreurs MySQLi, vous renforcez la robustesse, la sécurité et la maintenabilité de vos applications PHP connectées à MySQL ou MariaDB.

 Référence des fonctions PHP MySQLi

Par carabde | Mis à jour le 25 février 2026