Signatur
Beschreibung
SQLite3Exception ist eine spezialisierte Ausnahme-Klasse für Fehler, die bei der Verwendung der SQLite3-Erweiterung auftreten. Sie erbt von RuntimeException und kann daher überall dort gefangen werden, wo allgemeine Laufzeitfehler behandelt werden.
Die Klasse wird beispielsweise geworfen, wenn eine SQLite3-Datenbankdatei nicht geöffnet werden kann, eine SQL-Anweisung einen Syntaxfehler enthält, ein Constraint verletzt wird oder andere datenbankspezifische Fehler auftreten. Voraussetzung dafür ist, dass die SQLite3-Instanz mit aktivierten Ausnahmen (d. h. SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE) arbeitet oder explizit auf Ausnahme-Modus konfiguriert wurde.
Seit PHP 8.0 können SQLite3-Operationen so konfiguriert werden, dass Fehler als Ausnahmen geworfen werden (statt als Warnungen). In diesem Fall ist SQLite3Exception der geeignete Typ zum Abfangen. Die Methoden getMessage() und getCode() liefern den Fehlertext bzw. den SQLite-internen Fehlercode.
Für eine robuste Fehlerbehandlung empfiehlt es sich, SQLite3Exception spezifisch zu fangen, bevor generische Exception-Handler greifen, um datenbankbezogene Fehler von anderen Ausnahmen zu unterscheiden.
Beispiele
Abfangen einer SQLite3Exception beim Öffnen einer Datenbank
<?php
try {
// Versuche, eine Datenbankdatei zu öffnen, auf die kein Schreibzugriff besteht
$db = new SQLite3('/root/nicht_erlaubt.db', SQLITE3_OPEN_READWRITE);
} catch (SQLite3Exception $e) {
echo 'SQLite3-Fehler: ' . $e->getMessage() . PHP_EOL;
echo 'Fehlercode: ' . $e->getCode() . PHP_EOL;
}Abfangen eines SQL-Constraint-Fehlers
<?php
$db = new SQLite3(':memory:');
$db->enableExceptions(true);
$db->exec('CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT UNIQUE NOT NULL)');
$db->exec("INSERT INTO users (email) VALUES ('test@example.com')");
try {
// Doppelter Eintrag verletzt UNIQUE-Constraint
$db->exec("INSERT INTO users (email) VALUES ('test@example.com')");
} catch (SQLite3Exception $e) {
echo 'Datenbankfehler: ' . $e->getMessage() . PHP_EOL;
echo 'SQLite-Fehlercode: ' . $e->getCode() . PHP_EOL;
}
$db->close();// Wichtig · Fallstricke
Ausnahmen aktivieren: Standardmäßig erzeugt die SQLite3-Erweiterung PHP-Warnungen statt Ausnahmen. Um SQLite3Exception zu erhalten, muss SQLite3::enableExceptions(true) aufgerufen werden. Ohne diesen Aufruf werden Fehler als Warnungen ausgegeben und nicht als Ausnahmen geworfen.
Fehlercodes: Der von getCode() zurückgegebene Code entspricht dem nativen SQLite3-Fehlercode (z. B. SQLITE_CONSTRAINT = 19, SQLITE_CANTOPEN = 14). Diese Codes sind in der SQLite-Dokumentation aufgeführt.
Vererbungshierarchie: Da SQLite3Exception von RuntimeException erbt, wird sie auch von catch (RuntimeException $e) und catch (Exception $e) abgefangen. Für eine präzise Fehlerbehandlung sollte SQLite3Exception zuerst gefangen werden.