Signatur
Beschreibung
MongoDB\Driver\Exception\RuntimeException ist die Basisausnahme für alle Laufzeitfehler, die vom offiziellen MongoDB-PHP-Treiber (ext-mongodb) erzeugt werden. Sie erweitert PHPs eingebaute RuntimeException und implementiert das treibereigene Marker-Interface MongoDB\Driver\Exception\Exception, sodass alle treiberspezifischen Ausnahmen zentral abgefangen werden können.
Die Klasse dient primär als Elternklasse für spezialisierte Ausnahmen wie ConnectionException, AuthenticationException, WriteException und weitere. Direkt ausgelöst wird sie, wenn ein Fehler auftritt, der keiner dieser speziellen Kategorien zuzuordnen ist – etwa bei internen Treiberproblemen oder ungültigen Zuständen während einer Datenbankoperation.
Beim Aufbau robuster MongoDB-Anwendungen empfiehlt es sich, sowohl spezifische Unterklassen als auch RuntimeException als Fallback abzufangen. Da alle Treiber-Ausnahmen das Interface MongoDB\Driver\Exception\Exception implementieren, kann dieses Interface alternativ genutzt werden, um sämtliche Treiberfehler in einem einzigen catch-Block zu behandeln.
- Direkte Unterklassen umfassen u. a.
ConnectionException,AuthenticationException,BulkWriteExceptionundExecutionTimeoutException. - Die Eigenschaft
$errorLabels(verfügbar ab Treiber 1.6) enthält MongoDB-spezifische Fehler-Labels, die bei der Fehlerbehandlung in Transaktionen nützlich sind.
Beispiele
Abfangen von MongoDB-Laufzeitfehlern
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\Query;
use MongoDB\Driver\Exception\RuntimeException;
use MongoDB\Driver\Exception\Exception as MongoException;
try {
$manager = new Manager('mongodb://localhost:27017');
$query = new Query(['status' => 'active']);
$cursor = $manager->executeQuery('mydb.users', $query);
foreach ($cursor as $document) {
var_dump($document);
}
} catch (RuntimeException $e) {
// Spezifisch: MongoDB-Treiber-Laufzeitfehler
echo 'MongoDB-Laufzeitfehler: ' . $e->getMessage() . PHP_EOL;
echo 'Fehler-Code: ' . $e->getCode() . PHP_EOL;
} catch (\Exception $e) {
// Allgemeiner Fallback
echo 'Allgemeiner Fehler: ' . $e->getMessage() . PHP_EOL;
}Alle Treiber-Ausnahmen über das Interface abfangen
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\Command;
use MongoDB\Driver\Exception\Exception as MongoException;
use MongoDB\Driver\Exception\RuntimeException;
try {
$manager = new Manager('mongodb://invalid-host:27017',
['serverSelectionTimeoutMS' => 500]
);
$result = $manager->executeCommand('admin', new Command(['ping' => 1]));
} catch (MongoException $e) {
// Fängt ALLE MongoDB-Treiber-Ausnahmen ab (inkl. RuntimeException-Unterklassen)
echo get_class($e) . ': ' . $e->getMessage() . PHP_EOL;
// Prüfen ob Fehler-Labels vorhanden (z. B. bei Transaktionen)
if ($e instanceof RuntimeException && method_exists($e, 'hasErrorLabel')) {
if ($e->hasErrorLabel('TransientTransactionError')) {
echo 'Transaktion kann wiederholt werden.' . PHP_EOL;
}
}
}// Wichtig · Fallstricke
Fehler-Labels (ab Treiber 1.6): Die Methode hasErrorLabel(string $label) ist auf RuntimeException-Instanzen verfügbar und erlaubt die Prüfung auf MongoDB-spezifische Labels wie TransientTransactionError oder UnknownTransactionCommitResult. Dies ist besonders bei der Implementierung von Retry-Logik für Transaktionen relevant.
Vererbungshierarchie beachten: Da RuntimeException die Basisklasse aller spezifischen Treiber-Ausnahmen ist, fängt ein catch(RuntimeException)-Block auch alle Unterklassen ab. Für eine granulare Fehlerbehandlung sollten spezifischere Klassen zuerst abgefangen werden.
Nicht zu verwechseln mit PHPs eingebauter \RuntimeException – der vollständig qualifizierte Name MongoDB\Driver\Exception\RuntimeException muss verwendet bzw. korrekt importiert werden.