Signatur
Beschreibung
MongoDB\Driver\Exception\ConnectionException ist eine Ausnahme, die der MongoDB-Treiber für PHP wirft, wenn eine Verbindung zu einem MongoDB-Server nicht hergestellt oder aufrechterhalten werden kann. Sie erweitert MongoDB\Driver\Exception\RuntimeException und implementiert das Interface MongoDB\Driver\Exception\Exception.
Typische Ursachen für diese Ausnahme sind ein nicht erreichbarer MongoDB-Server (z. B. falscher Host oder Port, Firewall-Regeln), ein Timeout beim Verbindungsaufbau oder -abbau sowie Authentifizierungsprobleme auf Netzwerkebene. Sie dient als Basisklasse für spezialisierte Verbindungsfehler wie MongoDB\Driver\Exception\ConnectionTimeoutException.
Im Anwendungscode sollte diese Ausnahme in einem try/catch-Block abgefangen werden, um dem Benutzer eine sinnvolle Fehlermeldung zu präsentieren oder einen Wiederholungsversuch (Retry-Logik) einzuleiten. Da sie eine Elternklasse ist, fängt catch (ConnectionException $e) auch alle abgeleiteten Verbindungsausnahmen ab.
Es empfiehlt sich, im Fehlerfall niemals interne Verbindungsdetails (Host, Port, Zugangsdaten) an den Endbenutzer weiterzugeben, da diese sicherheitskritische Informationen enthalten können.
Beispiele
Verbindungsfehler abfangen und behandeln
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\Query;
use MongoDB\Driver\Exception\ConnectionException;
use MongoDB\Driver\Exception\Exception as MongoException;
try {
// Ungültiger Host, um einen Verbindungsfehler zu provozieren
$manager = new Manager('mongodb://invalid-host:27017', [
'connectTimeoutMS' => 2000,
'serverSelectionTimeoutMS' => 2000,
]);
$query = new Query([]);
$cursor = $manager->executeQuery('testdb.users', $query);
foreach ($cursor as $document) {
var_dump($document);
}
} catch (ConnectionException $e) {
// Verbindungsfehler – interne Details nur loggen, nicht anzeigen
error_log('MongoDB-Verbindungsfehler: ' . $e->getMessage());
echo 'Datenbankverbindung konnte nicht hergestellt werden. Bitte versuchen Sie es später erneut.';
} catch (MongoException $e) {
error_log('MongoDB-Fehler: ' . $e->getMessage());
echo 'Ein unerwarteter Datenbankfehler ist aufgetreten.';
}Retry-Logik bei Verbindungsabbrüchen
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\Command;
use MongoDB\Driver\Exception\ConnectionException;
function pingMongo(Manager $manager): bool
{
$command = new Command(['ping' => 1]);
$manager->executeCommand('admin', $command);
return true;
}
$maxVersuche = 3;
$versuch = 0;
$verbunden = false;
while ($versuch < $maxVersuche && !$verbunden) {
$versuch++;
try {
$manager = new Manager('mongodb://localhost:27017');
$verbunden = pingMongo($manager);
echo "Verbindung nach Versuch {$versuch} erfolgreich.\n";
} catch (ConnectionException $e) {
error_log("Versuch {$versuch} fehlgeschlagen: " . $e->getMessage());
if ($versuch < $maxVersuche) {
sleep(2); // Kurze Pause vor dem nächsten Versuch
} else {
echo 'MongoDB ist nach mehreren Versuchen nicht erreichbar.';
}
}
}// Wichtig · Fallstricke
Sicherheitshinweis: Die Exception-Nachricht (getMessage()) kann interne Informationen wie Hostnamen, Ports oder Fehlercodes des MongoDB-Servers enthalten. Geben Sie diese Informationen niemals ungefiltert an Endbenutzer weiter – loggen Sie sie nur serverseitig.
ConnectionException ist eine abstrakte Basisklasse für Verbindungsfehler. Konkrete Unterklassen wie MongoDB\Driver\Exception\ConnectionTimeoutException können für eine differenziertere Fehlerbehandlung gezielt abgefangen werden. Die Reihenfolge der catch-Blöcke ist dabei entscheidend: spezifischere Ausnahmen müssen vor der allgemeineren ConnectionException stehen.
Ab PHP-Treiber-Version 1.5 werden viele Verbindungsfehler intern durch den libmongoc-Fehlercode ergänzt, der über getCode() abgerufen werden kann und bei der Diagnose hilfreich ist.