Signatur
Beschreibung
Die Klasse MongoDB\Driver\Exception\CommandException repräsentiert einen Fehler, der auftritt, wenn der MongoDB-Server auf einen gesendeten Befehl mit einem Fehler-Dokument antwortet. Solche Fehler entstehen beispielsweise bei ungültigem BSON, fehlenden Berechtigungen, nicht vorhandenen Kollektionen oder Verstößen gegen Constraints wie eindeutige Indizes.
Im Gegensatz zu Verbindungsfehlern oder Netzwerkproblemen zeigt diese Exception an, dass der Server die Anfrage empfangen und verarbeitet hat, jedoch einen Fehler gemäß dem MongoDB-Protokoll zurückgemeldet hat. Über die Methode getResultDocument() kann das vollständige Fehler-Antwort-Dokument des Servers abgerufen werden, das zusätzliche Diagnoseinformationen enthält.
Die Klasse erbt von MongoDB\Driver\Exception\ServerException, die wiederum von MongoDB\Driver\Exception\RuntimeException abstammt. In der Ausnahmebehandlung kann gezielt auf CommandException geprüft werden, um serverseitige Befehlsfehler von anderen Fehlertypen (z. B. Verbindungsfehlern) zu unterscheiden.
Typische Anwendungsfälle für das Abfangen dieser Exception sind das Erkennen von Duplicate-Key-Fehlern (Fehlercode 11000), Berechtigungsverletzungen oder Schema-Validierungsfehler, sodass die Anwendung entsprechend reagieren kann.
Beispiele
Duplicate-Key-Fehler bei Einfüge-Befehl abfangen
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\BulkWrite;
use MongoDB\Driver\Exception\CommandException;
$manager = new Manager('mongodb://localhost:27017');
// Ersten Datensatz einfügen
$bulk = new BulkWrite();
$bulk->insert(['_id' => 1, 'name' => 'Alice']);
$manager->executeBulkWrite('testdb.users', $bulk);
// Zweiten Datensatz mit identischer _id einfügen (erzeugt Duplicate-Key-Fehler)
$bulk2 = new BulkWrite();
$bulk2->insert(['_id' => 1, 'name' => 'Bob']);
try {
$manager->executeBulkWrite('testdb.users', $bulk2);
} catch (CommandException $e) {
echo 'Fehlercode: ' . $e->getCode() . PHP_EOL;
echo 'Fehlermeldung: ' . $e->getMessage() . PHP_EOL;
// Vollständiges Fehler-Dokument des Servers abrufen
$resultDocument = $e->getResultDocument();
var_dump($resultDocument);
}Schema-Validierungsfehler gezielt behandeln
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\Command;
use MongoDB\Driver\BulkWrite;
use MongoDB\Driver\Exception\CommandException;
$manager = new Manager('mongodb://localhost:27017');
// Kollektion mit JSON-Schema-Validierung anlegen
try {
$manager->executeCommand('testdb', new Command([
'create' => 'validated_users',
'validator' => [
'$jsonSchema' => [
'bsonType' => 'object',
'required' => ['email'],
'properties' => [
'email' => ['bsonType' => 'string']
]
]
]
]));
} catch (CommandException $e) {
// Kollektion existiert möglicherweise bereits
}
// Datensatz ohne Pflichtfeld 'email' einfügen → Validierungsfehler
$bulk = new BulkWrite();
$bulk->insert(['name' => 'Charlie']); // 'email' fehlt!
try {
$manager->executeBulkWrite('testdb.validated_users', $bulk);
} catch (CommandException $e) {
echo 'Serverbefehl schlug fehl (Code ' . $e->getCode() . '): ' . $e->getMessage() . PHP_EOL;
$doc = $e->getResultDocument();
if (isset($doc->errInfo)) {
echo 'Detailinfo: ' . json_encode($doc->errInfo) . PHP_EOL;
}
}// Wichtig · Fallstricke
Fehlercode-Auswertung: Der Fehlercode (erreichbar über getCode()) entspricht dem MongoDB-Fehlercode aus dem Antwort-Dokument. Bekannte Codes sind z. B. 11000 für Duplicate-Key-Verletzungen oder 121 für Schema-Validierungsfehler. Eine Übersicht aller MongoDB-Fehlercodes findet sich in der offiziellen MongoDB-Dokumentation.
Ergebnis-Dokument: Die Methode getResultDocument() gibt das rohe BSON-Dokument zurück, das der Server als Fehlerantwort gesendet hat. Es kann zusätzliche Felder wie errInfo, keyPattern oder keyValue enthalten, die für die Fehlerdiagnose hilfreich sind.
Abgrenzung zu BulkWriteException: Bei Massenoperationen über executeBulkWrite() wird je nach Fehlerart statt einer CommandException eine MongoDB\Driver\Exception\BulkWriteException geworfen. Es empfiehlt sich, beide Exception-Typen in der Fehlerbehandlung zu berücksichtigen.