init

La funzione mysqli_init() alloca e inizializza un oggetto MySQLi senza aprire una connessione al database. È il primo passo di un processo di connessione in due fasi: si crea l'oggetto, si regolano le opzioni a basso livello e solo poi ci si connette con mysqli_real_connect(). Questa pagina ne spiega la sintassi, il valore restituito, quando è effettivamente necessaria e gli errori comuni in cui si incorre.

Sintassi

mysqli_init(): mysqli|false

Nello stile orientato agli oggetti non esiste un metodo dedicato — new mysqli() (chiamato senza argomenti) esegue la stessa inizializzazione:

$mysqli = mysqli_init();   // procedural
$mysqli = new mysqli();    // object-oriented equivalent

• Parametri: nessuno.
• Valore restituito: un oggetto mysqli nuovo e non connesso in caso di successo, oppure false in caso di errore. (A partire da PHP 8.1 la forma procedurale è solo un alias sottile per new mysqli() e genera un'eccezione in caso di errore invece di restituire false, in linea con le impostazioni di mysqli_report().)

Perché esiste mysqli_init()

Quando si chiama new mysqli("localhost", "user", "pass", "db") con argomenti, PHP inizializza l'oggetto e si connette in un unico passaggio. È comodo, ma non lascia spazio per configurare opzioni che devono essere impostate prima dell'handshake — timeout di connessione, un comando iniziale SET NAMES, SSL o il supporto a local-infile.

mysqli_init() separa queste due fasi:

1. Inizializzare l'oggetto con mysqli_init().
2. Configurarlo con mysqli_options() (e SSL tramite mysqli_ssl_set() se necessario).
3. Connettersi con mysqli_real_connect().

Se non si ha bisogno di opzioni pre-connessione, si può saltare completamente mysqli_init() e passare le credenziali direttamente a new mysqli() — è più breve ed egualmente corretto.

Esempio di base

Questo è il flusso di lavoro procedurale canonico. Si noti che mysqli_options() si trova tra init e connect:

<?php
$mysqli = mysqli_init();

if (!$mysqli) {
    die("mysqli_init() failed");
}

// Run on every new connection — must be set before connecting.
mysqli_options($mysqli, MYSQLI_INIT_COMMAND, "SET NAMES 'utf8mb4'");

// Give up after 5 seconds instead of hanging.
mysqli_options($mysqli, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

if (!mysqli_real_connect($mysqli, "localhost", "username", "password", "database")) {
    echo "Failed to connect to MySQL: " . mysqli_connect_error();
    exit;
}

echo "Connected. Server version: " . mysqli_get_server_info($mysqli);

mysqli_close($mysqli);
?>

Il flusso è: creare l'oggetto, impostare le opzioni che devono precedere l'handshake, quindi connettersi. Si verifica il risultato di mysqli_real_connect() e si legge il motivo dell'errore con mysqli_connect_error(). Infine mysqli_close() rilascia la connessione.

Importante: le opzioni passate a mysqli_options() hanno effetto solo se impostate prima di mysqli_real_connect(). Chiamarle dopo la connessione non ha alcun effetto.

Equivalente orientato agli oggetti

Lo stesso programma in stile OOP — più chiaro nelle codebase moderne:

<?php
$mysqli = new mysqli();   // unconnected, same as mysqli_init()

$mysqli->options(MYSQLI_INIT_COMMAND, "SET NAMES 'utf8mb4'");
$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

if (!$mysqli->real_connect("localhost", "username", "password", "database")) {
    echo "Failed to connect: " . $mysqli->connect_error;
    exit;
}

echo "Connected. Server version: " . $mysqli->server_info;
$mysqli->close();
?>

Opzioni pre-connessione comuni

Alcune delle opzioni che si impostano tipicamente dopo mysqli_init():

Per TLS, configurarlo con mysqli_ssl_set() (vedi mysqli_ssl_set()) prima di mysqli_real_connect().

Errori comuni

• Non apre la connessione. Un handle restituito da mysqli_init() non può essere usato per le query finché mysqli_real_connect() non ha avuto successo.
• L'ordine è importante. Impostare ogni opzione pre-connessione prima di connettersi, altrimenti verrà ignorata silenziosamente.
• Preferire set_charset() per il charset. Usare MYSQLI_INIT_COMMAND con SET NAMES funziona, ma mysqli_set_charset() (chiamata dopo la connessione) è il metodo raccomandato per impostare il charset della connessione, perché la libreria client deve conoscere il charset per un corretto escaping.

Funzioni correlate

• mysqli_real_connect() — apre la connessione su un oggetto inizializzato.
• mysqli_options() — imposta le opzioni pre-connessione.
• mysqli_connect_errno() / mysqli_connect_error() — esamina gli errori di connessione.
• La panoramica dell'estensione mysqli — come si incastrano tutti i pezzi.

Conclusione

mysqli_init() serve a un unico scopo: ottenere un oggetto MySQLi non connesso per poter configurare opzioni a basso livello prima dell'handshake. Se non si hanno bisogno di tali opzioni, new mysqli(...) con le credenziali è il percorso più semplice. Ricorrere a mysqli_init() quando si ha bisogno di un timeout di connessione, di un comando di init o di SSL — poi mysqli_options() → mysqli_real_connect() completa la sequenza.

Esercizio