connect_error

La fonction mysqli_connect_error() retourne une string décrivant la dernière erreur de connexion levée par MySQLi. C'est le premier réflexe à avoir lorsque mysqli_connect() échoue et que vous devez savoir pourquoi — mauvais hôte, identifiants incorrects, base de données manquante ou serveur inaccessible. Cette page explique ce que retourne la fonction, en quoi elle diffère de mysqli_connect_errno() associée, et comment l'utiliser correctement dans les API MySQLi procédurale et orientée objet.

Syntaxe

mysqli_connect_error() ne prend aucun argument car, par conception, une tentative de connexion échouée ne produit pas d'objet MySQLi utilisable — il n'y a donc rien à lui passer.

mysqli_connect_error(): string|null

Valeur de retour

• Une string contenant le message d'erreur lisible par l'humain du dernier appel à mysqli_connect() / mysqli_real_connect().
• null si aucune erreur n'est survenue (la connexion a réussi).

Comme elle retourne null en cas de succès, vous ne devez l'appeler qu'après avoir confirmé l'échec de la connexion.

Comment utiliser mysqli_connect_error() (style procédural)

Dans l'API procédurale, mysqli_connect() retourne false lorsque la connexion échoue. Vérifiez d'abord cette valeur de retour, puis lisez le message :

<?php
$mysqli = mysqli_connect("localhost", "username", "password", "database");

if (!$mysqli) {
    // Connection failed — mysqli_connect_error() now holds the reason
    echo "Failed to connect to MySQL: " . mysqli_connect_error();
    exit();
}

echo "Connected successfully";

// ... run your queries here ...

mysqli_close($mysqli);
?>

Si les identifiants sont incorrects, vous verrez quelque chose comme :

Failed to connect to MySQL: Access denied for user 'username'@'localhost' (using password: YES)

Style orienté objet : connect_error vs connect_errno

Lorsque vous créez la connexion avec new mysqli(...), la fonction procédurale mysqli_connect_error() fonctionne toujours, mais il est plus idiomatique de lire les propriétés correspondantes sur l'objet :

• $mysqli->connect_error — le message d'erreur (string, ou null en cas de succès).
• $mysqli->connect_errno — le numéro d'erreur (un code entier, 0 en cas de succès).

Le numéro est pratique pour brancher selon un échec spécifique ; le message est destiné aux humains et aux journaux.

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");

if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
    exit();
}

echo "Connected successfully";

$mysqli->close();
?>

Pour une description complète du code numérique, consultez mysqli_connect_errno().

Recommandé : laisser MySQLi lever des exceptions

Vérifier manuellement la valeur de retour après chaque connexion est facile à oublier. Depuis PHP 8.1, MySQLi lève une mysqli_sql_exception en cas d'échec par défaut, ce qui vous permet de gérer les erreurs avec un bloc try/catch normal. C'est le modèle recommandé pour le nouveau code :

<?php
// Enable exception mode explicitly (the default since PHP 8.1)
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

try {
    $mysqli = new mysqli("localhost", "username", "password", "database");
    echo "Connected successfully";
    $mysqli->close();
} catch (mysqli_sql_exception $e) {
    // $e->getMessage() carries the same text connect_error would return
    echo "Failed to connect to MySQL: " . $e->getMessage();
    exit();
}
?>

Avec le mode exception activé, connect_error est rarement lu directement — le message transite à l'intérieur de l'exception à la place.

Pièges courants

• N'appelez pas cette méthode sur l'objet de connexion que vous n'avez pas réussi à obtenir. En cas d'échec d'une connexion procédurale, $mysqli vaut false, donc $mysqli->connect_error provoquerait une erreur. Utilisez la fonction autonome mysqli_connect_error() (sans argument) dans ce cas.
• Elle reflète la dernière tentative. Si vous ouvrez plusieurs connexions, la valeur appartient à l'appel de connexion le plus récent, pas à un handle spécifique.
• Ne jamais afficher les erreurs brutes aux utilisateurs en production. Les messages de connexion peuvent divulguer des noms d'hôtes et des noms d'utilisateurs — journalisez-les et affichez un message générique à la place.

Conclusion

mysqli_connect_error() est un outil de débogage petit mais essentiel : il vous indique exactement pourquoi une connexion MySQLi a échoué. Combinez-le avec mysqli_connect_errno() lorsque vous avez besoin du code numérique, préférez les propriétés OO connect_error/connect_errno lorsque vous vous connectez avec new mysqli(), et pour les nouveaux projets, optez pour la gestion des erreurs par exceptions. Pour en savoir plus sur l'ouverture des connexions, consultez mysqli_connect() et la présentation de MySQLi.

Pratique