Signatur
Beschreibung
mysqli_stmt_sqlstate() liefert einen fünfstelligen SQLSTATE-Code als Zeichenkette, der den Fehlerstatus der zuletzt an einem mysqli_stmt-Objekt ausgeführten Operation beschreibt. SQLSTATE-Codes sind im ANSI-SQL- und ODBC-Standard definiert und ermöglichen eine datenbankherstellerunabhängige Fehlerauswertung.
Ein Rückgabewert von '00000' bedeutet, dass kein Fehler aufgetreten ist. Begann der Code mit '01', handelt es sich um eine Warnung. Alle anderen Werte weisen auf einen echten Fehler hin. Im Gegensatz zum MySQL-spezifischen Fehlercode (vgl. mysqli_stmt_errno()) erlaubt der SQLSTATE-Code eine portablere Fehlerbehandlung.
Die Funktion ist besonders nützlich, wenn derselbe Fehlerbehandlungscode für mehrere Datenbanksysteme verwendet werden soll oder wenn Fehlerklassen (z. B. Constraint-Verletzungen mit '23000') erkannt werden sollen, ohne auf herstellerspezifische Fehlernummern zu prüfen.
In der objektorientierten Variante steht das Ergebnis über die Eigenschaft $stmt->sqlstate zur Verfügung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $statement Pflicht | mysqli_stmt | Ein mysqli_stmt-Objekt, das durch mysqli_prepare() oder mysqli::prepare() erzeugt wurde. |
Rückgabewert
'00000' bedeutet kein Fehler. Bei einem Fehler enthält der Rückgabewert den entsprechenden SQLSTATE-Code (z. B. '23000' für eine Integritätsverletzung). Die Funktion gibt immer einen String zurück, niemals false oder null.Beispiele
SQLSTATE-Code nach fehlerhafter Ausführung auswerten
<?php
$mysqli = new mysqli('localhost', 'user', 'password', 'testdb');
if ($mysqli->connect_errno) {
die('Verbindungsfehler: ' . $mysqli->connect_error);
}
// Tabelle mit UNIQUE-Constraint anlegen (falls nicht vorhanden)
$mysqli->query('CREATE TABLE IF NOT EXISTS users (id INT PRIMARY KEY AUTO_INCREMENT, email VARCHAR(255) UNIQUE NOT NULL)');
// Ersten Datensatz einfügen
$stmt = $mysqli->prepare('INSERT INTO users (email) VALUES (?)');
$stmt->bind_param('s', $email);
$email = 'test@example.com';
$stmt->execute();
// Duplikat einfügen → Constraint-Verletzung
$stmt->execute();
$sqlstate = mysqli_stmt_sqlstate($stmt);
echo 'SQLSTATE: ' . $sqlstate . PHP_EOL;
if ($sqlstate === '23000') {
echo 'Fehler: Doppelter Eintrag – E-Mail-Adresse bereits vorhanden.' . PHP_EOL;
}
$stmt->close();
$mysqli->close();Objektorientierte Schreibweise mit allgemeiner Fehlerklassenerkennung
<?php
$mysqli = new mysqli('localhost', 'user', 'password', 'testdb');
$stmt = $mysqli->prepare('SELECT * FROM nicht_vorhandene_tabelle WHERE id = ?');
if (!$stmt) {
// prepare() selbst ist fehlgeschlagen – SQLSTATE über mysqli-Objekt
echo 'Prepare-Fehler SQLSTATE: ' . $mysqli->sqlstate . PHP_EOL;
} else {
$id = 1;
$stmt->bind_param('i', $id);
$stmt->execute();
$sqlstate = $stmt->sqlstate;
echo 'SQLSTATE nach execute(): ' . $sqlstate . PHP_EOL;
// Einfache Klassenerkennung anhand des ersten Zeichens
$klasse = substr($sqlstate, 0, 2);
match ($klasse) {
'00' => print('Kein Fehler.' . PHP_EOL),
'01' => print('Warnung aufgetreten.' . PHP_EOL),
default => print('Fehler der Klasse ' . $klasse . ' aufgetreten.' . PHP_EOL),
};
$stmt->close();
}
$mysqli->close();// Wichtig · Fallstricke
Hinweis zur Verfügbarkeit: Nicht alle MySQL-Fehlersituationen werden auf einen standardisierten SQLSTATE-Code abgebildet. In solchen Fällen gibt MySQL den generischen Code 'HY000' zurück. Für detaillierte Fehlermeldungen sollte zusätzlich mysqli_stmt_error() bzw. mysqli_stmt_errno() ausgewertet werden.
Prepare-Fehler: Schlägt mysqli_prepare() fehl, steht kein mysqli_stmt-Objekt zur Verfügung. In diesem Fall muss der SQLSTATE-Code über mysqli_sqlstate() am Verbindungs-Objekt abgefragt werden.
Objektorientierte Alternative: Statt der prozeduralen Funktion kann die Eigenschaft $stmt->sqlstate verwendet werden – beide Varianten liefern identische Ergebnisse.