connect_error

La funzione mysqli_connect_error() restituisce una string che descrive l'ultimo errore di connessione generato da MySQLi. È la prima cosa a cui ricorrere quando mysqli_connect() fallisce e si vuole sapere perché — host errato, credenziali sbagliate, database mancante o server non raggiungibile. Questa pagina spiega cosa restituisce la funzione, come si differenzia dalla correlata mysqli_connect_errno() e come usarla correttamente sia nell'API MySQLi procedurale che in quella orientata agli oggetti.

Sintassi

mysqli_connect_error() non accetta argomenti perché, per progettazione, un tentativo di connessione fallito non produce un oggetto MySQLi utilizzabile — quindi non c'è nulla da passarle.

mysqli_connect_error(): string|null

Valore restituito

• Una string con il messaggio di errore leggibile dall'utente relativo alla chiamata più recente a mysqli_connect() / mysqli_real_connect().
• null se non si è verificato alcun errore (la connessione è riuscita).

Poiché restituisce null in caso di successo, è opportuno chiamarla solo dopo aver confermato che la connessione è fallita.

Come usare mysqli_connect_error() (stile procedurale)

Nell'API procedurale, mysqli_connect() restituisce false quando la connessione fallisce. Controlla prima quel valore di ritorno, poi leggi il messaggio:

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

Se le credenziali sono errate vedrai qualcosa del tipo:

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

Stile orientato agli oggetti: connect_error vs connect_errno

Quando si crea la connessione con new mysqli(...), la funzione procedurale mysqli_connect_error() funziona ancora, ma è più idiomatico leggere le proprietà corrispondenti sull'oggetto:

• $mysqli->connect_error — il messaggio di errore (string, o null in caso di successo).
• $mysqli->connect_errno — il numero dell'errore (un codice intero, 0 in caso di successo).

Il numero è utile per ramificare su un errore specifico; il messaggio è per gli esseri umani e i log.

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

Per un'analisi completa del codice numerico, vedi mysqli_connect_errno().

Consigliato: far lanciare eccezioni a MySQLi

Verificare manualmente il valore di ritorno dopo ogni connessione è facile da dimenticare. Da PHP 8.1, MySQLi lancia una mysqli_sql_exception in caso di errore per impostazione predefinita, il che consente di gestire gli errori con un normale blocco try/catch. Questo è il pattern consigliato per il nuovo codice:

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

Con la modalità eccezioni attiva, connect_error viene raramente letta direttamente — il messaggio viaggia all'interno dell'eccezione.

Errori comuni

• Non chiamarla sull'oggetto connessione che non si è riusciti a ottenere. In caso di connessione procedurale fallita, $mysqli è false, quindi $mysqli->connect_error darebbe errore. Usa la funzione standalone mysqli_connect_error() (senza argomenti) in quel caso.
• Riflette l'ultimo tentativo. Se si aprono più connessioni, il valore appartiene alla chiamata di connessione più recente, non a un handle specifico.
• Non mostrare mai errori grezzi agli utenti finali in produzione. I messaggi di connessione possono rivelare nomi di host e nomi utente — registrali nel log e mostra invece un messaggio generico.

Conclusione

mysqli_connect_error() è uno strumento di debug piccolo ma essenziale: indica esattamente perché una connessione MySQLi è fallita. Usala insieme a mysqli_connect_errno() quando è necessario il codice numerico, preferisci le proprietà OO connect_error/connect_errno quando ti connetti con new mysqli(), e per i nuovi progetti opta per la gestione degli errori basata su eccezioni. Per saperne di più sull'apertura delle connessioni, vedi mysqli_connect() e la panoramica MySQLi.

Esercitazione