init

Die Funktion mysqli_init() reserviert und initialisiert ein MySQLi-Objekt ohne eine Datenbankverbindung zu öffnen. Sie ist der erste Schritt eines zweistufigen Verbindungsprozesses: Das Objekt wird erstellt, seine Low-Level-Optionen werden konfiguriert, und erst dann wird mit mysqli_real_connect() verbunden. Diese Seite erläutert die Syntax, den Rückgabewert, wann man diese Funktion tatsächlich benötigt und welche häufigen Fallstricke es gibt.

Syntax

mysqli_init(): mysqli|false

Im objektorientierten Stil gibt es keine dedizierte Methode — new mysqli() (ohne Argumente aufgerufen) führt dieselbe Initialisierung durch:

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

• Parameter: keine.
• Rückgabewert: ein neues, unverbundenes mysqli-Objekt bei Erfolg oder false bei Fehler. (Seit PHP 8.1 ist die prozedurale Form nur ein dünner Alias für new mysqli() und wirft bei Fehler eine Exception, anstatt false zurückzugeben — entsprechend den mysqli_report()-Einstellungen.)

Wozu mysqli_init() dient

Wenn man new mysqli("localhost", "user", "pass", "db") mit Argumenten aufruft, initialisiert PHP das Objekt und verbindet sich in einem einzigen Schritt. Das ist praktisch, lässt aber kein Zeitfenster für die Konfiguration von Optionen, die vor dem Handshake gesetzt werden müssen — Verbindungs-Timeouts, einen initialen SET NAMES-Befehl, SSL oder Local-Infile-Unterstützung.

mysqli_init() trennt diese zwei Phasen voneinander:

1. Initialisieren des Objekts mit mysqli_init().
2. Konfigurieren mit mysqli_options() (und SSL über mysqli_ssl_set() falls nötig).
3. Verbinden mit mysqli_real_connect().

Wenn keine Pre-Connection-Optionen benötigt werden, kann mysqli_init() komplett übersprungen werden — Zugangsdaten werden direkt an new mysqli() übergeben, was kürzer und genauso korrekt ist.

Grundlegendes Beispiel

Dies ist der kanonische prozedurale Ablauf. Beachten Sie, dass mysqli_options() zwischen Init und Connect steht:

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

Der Ablauf ist: Objekt erstellen, Optionen setzen, die vor dem Handshake erforderlich sind, dann verbinden. Das Ergebnis von mysqli_real_connect() wird überprüft und der Fehlergrund mit mysqli_connect_error() ausgelesen. Abschließend gibt mysqli_close() die Verbindung frei.

Wichtig: Optionen, die an mysqli_options() übergeben werden, treten nur dann in Kraft, wenn sie vor mysqli_real_connect() gesetzt werden. Ein Aufruf nach dem Verbinden hat keine Wirkung.

Objektorientiertes Äquivalent

Dasselbe Programm im OOP-Stil — klarer in modernen Codebasen:

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

Häufige Pre-Connection-Optionen

Einige der Optionen, die typischerweise nach mysqli_init() gesetzt werden:

Für TLS wird es mit mysqli_ssl_set() konfiguriert (siehe mysqli_ssl_set()) — vor mysqli_real_connect().

Häufige Fallstricke

• Es wird keine Verbindung hergestellt. Ein Handle von mysqli_init() ist für Abfragen nicht nutzbar, bis mysqli_real_connect() erfolgreich war.
• Die Reihenfolge ist entscheidend. Jede Pre-Connection-Option muss vor dem Verbinden gesetzt werden, andernfalls wird sie stillschweigend ignoriert.
• set_charset() für den Zeichensatz bevorzugen. MYSQLI_INIT_COMMAND mit SET NAMES funktioniert, aber mysqli_set_charset() (nach dem Verbinden aufgerufen) ist die empfohlene Methode zur Einstellung des Verbindungszeichensatzes, da die Client-Bibliothek den Zeichensatz für korrekte Escapierung kennen muss.

Verwandte Funktionen

• mysqli_real_connect() — öffnet die Verbindung auf einem initialisierten Objekt.
• mysqli_options() — setzt die Pre-Connection-Optionen.
• mysqli_connect_errno() / mysqli_connect_error() — untersucht Verbindungsfehler.
• Die MySQLi-Erweiterung im Überblick — wie alle Teile zusammenspielen.

Fazit

mysqli_init() hat genau eine Aufgabe: ein unverbundenes MySQLi-Objekt bereitzustellen, damit Low-Level-Optionen vor dem Handshake konfiguriert werden können. Wenn diese Optionen nicht benötigt werden, ist new mysqli(...) mit Zugangsdaten der einfachere Weg. mysqli_init() wird verwendet, wenn ein Verbindungs-Timeout, ein Init-Befehl oder SSL benötigt wird — dann vervollständigt mysqli_options() → mysqli_real_connect() die Sequenz.

Übungen