connect_errno

La funzione mysqli_connect_errno() restituisce il codice di errore dell'ultimo tentativo di connessione MySQLi, oppure 0 se non si è verificato alcun errore. È il metodo standard per verificare se una chiamata a mysqli_connect() (o al costruttore new mysqli()) è andata a buon fine prima di eseguire query. Questa pagina illustra la sintassi, il valore restituito, le differenze rispetto alle funzioni correlate e le insidie da evitare.

Perché il controllo della connessione è importante

Quando una connessione MySQLi fallisce, l'handle $mysqli viene comunque restituito, ma non è utilizzabile. Se si salta il controllo ed si esegue immediatamente una query, PHP emette un avviso e lo script continua a girare con una connessione interrotta — producendo spesso errori a valle difficili da interpretare. Chiamare mysqli_connect_errno() subito dopo la connessione permette di fallire rapidamente con un messaggio chiaro.

Un dettaglio fondamentale: mysqli_connect_errno() è una funzione standalone. Va chiamata senza argomenti — legge lo stato globale dell'ultimo tentativo di connessione, non un oggetto di connessione specifico.

Sintassi

mysqli_connect_errno(): int

Il codice numerico corrisponde a un numero di errore del client MySQL/MariaDB — ad esempio 1045 per accesso negato o 2002 per connessione rifiutata. Per il messaggio leggibile, abbinarlo a mysqli_connect_error().

Utilizzo di base (stile procedurale)

Chiamare la funzione immediatamente dopo mysqli_connect() e uscire anticipatamente se è diverso da zero:

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

if (mysqli_connect_errno()) {
    echo "Failed to connect to MySQL: " . mysqli_connect_error();
    exit();
}

echo "Connected successfully.";
// execute queries using $mysqli

mysqli_close($mysqli);
?>

Se le credenziali sono errate, viene stampato qualcosa come Failed to connect to MySQL: Access denied for user 'username'@'localhost' e lo script si interrompe. In caso di successo stampa Connected successfully.. Poiché il codice di errore è truthy solo quando è diverso da zero, if (mysqli_connect_errno()) si legge naturalmente come "se si è verificato un errore."

Stile orientato agli oggetti

Quando si usa la classe mysqli, l'equivalente di mysqli_connect_errno() è la proprietà connect_errno dell'oggetto. Va letta nello stesso modo — subito dopo la costruzione:

<?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.";
// execute queries using $mysqli

$mysqli->close();
?>

Qui $mysqli->connect_errno contiene il codice numerico e $mysqli->connect_error contiene il messaggio — combinarli (es. (1045) Access denied...) rende le voci di log facili da ricercare con grep.

connect_errno vs. funzioni correlate

È facile confondere le funzioni di errore di connessione con le funzioni di errore generali di MySQLi. Riguardano aspetti diversi:

In sintesi: usare connect_errno/connect_error per l'handshake, e errno/error per le query una volta connessi.

Insidie comuni

• Riflette solo l'ultimo tentativo. Se si aprono più connessioni, mysqli_connect_errno() riporta l'ultima. Per una precisione per-oggetto nel codice OO, preferire $mysqli->connect_errno.
• Controllarlo prima della prima query, non dopo. Una volta eseguita una query, mysqli_connect_errno() riflette ancora il tentativo di connessione, ma confonderlo con mysqli_errno() porta a bug.
• Un controllo truthy è sufficiente. Raramente è necessario confrontare il codice con un numero specifico; if (mysqli_connect_errno()) copre ogni tipo di errore.
• Considerare le eccezioni in alternativa. A partire da PHP 8.1, MySQLi lancia mysqli_sql_exception sugli errori per impostazione predefinita (mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT)), quindi una connessione fallita genera un'eccezione anziché restituire un handle non valido. In quella modalità si racchiude la connessione in un blocco try/catch invece di interrogare connect_errno.

Funzioni correlate

• mysqli_connect() — apre una connessione.
• mysqli_connect_error() — messaggio per l'ultimo errore di connessione.
• mysqli_real_connect() — apre una connessione con opzioni aggiuntive.
• Panoramica dell'estensione MySQLi — contesto più ampio su MySQLi.

Conclusione

mysqli_connect_errno() è il controllo più rapido e affidabile che una connessione MySQLi sia avvenuta correttamente: un valore restituito diverso da zero indica che l'handshake è fallito, 0 significa che si può procedere con le query. Abbinarlo a mysqli_connect_error() per messaggi leggibili, tenerlo distinto da mysqli_errno() a livello di query, e su PHP 8.1+ considerare try/catch con la modalità eccezione come alternativa moderna.

Pratica