Guide complet sur la fonction mysqli_sqlstate en PHP

Lorsque vous travaillez avec MySQL en PHP via l'extension mysqli, vous avez besoin d'un moyen fiable pour savoir pourquoi une requête a échoué. La fonction mysqli_sqlstate() renvoie le code d'erreur SQLSTATE de la dernière opération MySQL exécutée — un code standardisé et portable qui indique la catégorie d'une erreur.

Ce guide explique ce qu'est SQLSTATE, en quoi mysqli_sqlstate() diffère de mysqli_errno() spécifique à MySQL, les codes que vous rencontrerez le plus souvent, et comment l'utiliser correctement (y compris dans le mode moderne basé sur les exceptions de PHP).

Qu'est-ce que SQLSTATE ?

SQLSTATE est un code d'erreur de cinq caractères défini par le standard SQL ANSI/ISO. Comme il fait partie du standard plutôt qu'être une invention de MySQL, le même code signifie à peu près la même chose sur différents moteurs de base de données, ce qui le rend plus portable que les numéros d'erreur spécifiques au fournisseur.

Les cinq caractères sont divisés en deux parties :

• Les deux premiers caractères sont la classe de l'erreur. Par exemple, la classe 00 signifie succès, 01 signifie un avertissement, et 42 signifie une violation de syntaxe ou de règle d'accès.
• Les trois derniers caractères sont la sous-classe, qui précise davantage le problème.

Ainsi, 42S02 ("table de base ou vue introuvable") appartient à la classe 42 (violation de syntaxe/accès) avec la sous-classe S02.

Syntaxe

mysqli_sqlstate(mysqli $connection): string

mysqli_sqlstate() prend un seul argument — l'objet de connexion renvoyé par mysqli_connect() — et retourne une chaîne :

• Une chaîne vide mais remplie de zéros "00000" lorsque la dernière opération a réussi.
• Un code de cinq caractères tel que "42S02" lorsqu'une erreur s'est produite.

En style orienté objet, il s'agit de la méthode $connection->sqlstate.

SQLSTATE vs. mysqli_errno : lequel utiliser ?

Ces deux fonctions répondent à des questions différentes, et vous souhaitez souvent les deux :

Règle générale : basez votre logique sur mysqli_sqlstate() lorsque vous voulez un code qui survive à une migration de base de données, et utilisez mysqli_errno() lorsque vous avez besoin d'une distinction spécifique à MySQL. Utilisez mysqli_error() pour le message que vous journalisez.

Un exemple complet

Le fragment ci-dessous se connecte, exécute une requête sur une table qui n'existe pas, et affiche les trois diagnostics pour que vous puissiez voir comment ils se correspondent :

<?php

$connection = mysqli_connect('localhost', 'user', 'password', 'mydatabase');

if (!$connection) {
    die('Connection failed: ' . mysqli_connect_error());
}

$sql = "SELECT * FROM table_that_does_not_exist";

if (mysqli_query($connection, $sql)) {
    echo "Query executed successfully.";
} else {
    echo "SQLSTATE: " . mysqli_sqlstate($connection) . "\n";
    echo "Errno:    " . mysqli_errno($connection) . "\n";
    echo "Message:  " . mysqli_error($connection) . "\n";
}

// Typical output:
// SQLSTATE: 42S02
// Errno:    1146
// Message:  Table 'mydatabase.table_that_does_not_exist' doesn't exist

Remarquez comment le SQLSTATE portable (42S02) et le numéro d'erreur spécifique à MySQL (1146) décrivent le même problème à deux niveaux de détail.

Codes SQLSTATE courants

Voici les codes que vous êtes le plus susceptible de gérer dans votre travail quotidien PHP/MySQL :

Brancher sur ces codes vous permet de réagir de manière significative — par exemple, traiter une erreur de clé dupliquée 23000 comme "cet enregistrement existe déjà" plutôt que comme un échec fatal :

<?php

$sql = "INSERT INTO users (email) VALUES ('[email protected]')";

if (!mysqli_query($connection, $sql)) {
    if (mysqli_sqlstate($connection) === '23000') {
        echo "That email address is already registered.";
    } else {
        echo "Unexpected database error: " . mysqli_error($connection);
    }
}

Utilisation avec le mode exception

Le PHP moderne (8.1+) active le rapport d'erreurs MySQL par défaut, de sorte qu'une requête échouée lève une mysqli_sql_exception plutôt que de retourner false. Dans ce mode, vous lisez le SQLSTATE depuis la méthode getSqlState() de l'exception plutôt qu'en appelant mysqli_sqlstate() après coup :

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

try {
    $connection = mysqli_connect('localhost', 'user', 'password', 'mydatabase');
    mysqli_query($connection, "SELECT * FROM missing_table");
} catch (mysqli_sql_exception $e) {
    echo "SQLSTATE: " . $e->getSqlState() . "\n"; // e.g. 42S02
    echo "Code:     " . $e->getCode() . "\n";     // e.g. 1146
    echo "Message:  " . $e->getMessage();
}

Si vous appelez mysqli_sqlstate() directement après qu'une exception a déjà été interceptée, cela fonctionne toujours — mais dans un bloc try/catch, lire le code depuis l'objet exception est plus propre et évite de requêter à nouveau l'état de la connexion.

Points à surveiller

• Il ne reflète que la dernière opération. Chaque nouvelle requête écrase le SQLSTATE précédent. Lisez-le immédiatement après l'appel qui vous intéresse — avant d'exécuter quoi que ce soit d'autre sur la même connexion.
• "00000" signifie succès, pas une erreur. Ne traitez pas un retour non vide comme un échec ; une opération réussie renvoie la chaîne tout-zéro, pas "".
• Une connexion échouée n'a pas de SQLSTATE. Si mysqli_connect() lui-même échoue, il n'y a pas d'objet de connexion à interroger, alors utilisez mysqli_connect_error() pour les problèmes de connexion.

Conclusion

mysqli_sqlstate() vous fournit le code SQLSTATE portable et conforme aux standards pour la dernière opération MySQL, en complément de mysqli_errno() spécifique à MySQL et de mysqli_error() lisible par l'homme. Basez-vous sur SQLSTATE lorsque vous souhaitez une gestion des erreurs indépendante de la base de données, passez à getSqlState() de l'exception lorsque vous exécutez en mode exception par défaut de PHP, et lisez toujours le code juste après l'opération qu'il décrit.

Pratique